NodeJS framework to build any website or api with total control and without limiting practices.
- Start a new Website or API quickly and easy
- It is just a tool. It is NOT an opinionated framework that forces you to do things in some specific way
- Built in top of Express. If you already know Express, using Spacehorn will be a breeze
With npm:
$ npm install spacehorn
With yarn:
$ yarn add spacehorn
This example mounts a simple server that listens on the default port 3000
const Website = new Spacehorn({
name: 'Awesome Website',
routes: [
{
path: '/',
method: 'get',
exec(drawer, req, res){
res.send('Hello World')
}
}
]
});
Website.attend();
After running your application, you will see in your terminal the following:
----------------------------------------
Awesome Website is serving on port 3000
Then you can go to localhost:3000 and see "Hello World" being printed.
Spacehorn has some CLI commands to easily create and start a new application.
Install it globally on your system:
$ npm i -g spacehorn
You can:
### Create a new scaffold for an API with PostgreSQL
spacehorn --arch psql-api
yarn (or npm install)
npm start (A ready server will start listening with a demo endpoint "localhost:3000/status")
### Create controllers
cd app/controllers
spacehorn -c users (new dir "users" with controller files for all http verbs is created)
spacehorn -c users -n QueryUsers (creates a QueryUsers.js controller inside "users" dir)
spacehorn -c cars -n NewCar (new dir "cars" with a single NewCar.js controller)
Specify a public directory for your assets.
const Website = new Spacehorn({
name: 'Awesome Website',
publicDir: path.join(__dirname, 'public')
...
Just like publicDir, specify the directory where your views live.
const Website = new Spacehorn({
name: 'Awesome Website',
viewsDir: path.join(__dirname, 'web', 'views')
...
If you specify a viewsDir
, viewsEngine
will be required.
It must be passed as a String declaring the templates extension. Or, as an Object with ext
and engineFunc
.
ext
It is the extension of your templates.
engineFunc
This is the function handler to manage any custom template engine.
The engineFunc
is not required if you are using any of the following engines in this list.
Spacehorn makes use of Express. Any engine that Express supports is ready to be used.
This are the routes you want to set for your application passed as an array. Each route in format:
{
method: String (one of 'get', 'post', 'put', 'delete')
path: String (the path of the route, e.g: '/about')
view: String (the view to be used taken from the specified viewsDir. E.g: 'about')
exec: Function(drawer, req, res)
}
The exec
function params available are the drawer
, the request
and response
.
The drawer
:
It is meant to be a toolset that comes with the method
, path
and view
of the route. It has all the params (path params, query, body) in a single params
key. And also, comes with an http
util to be used. (There is more about the drawer.http
below).
If you specify a Database instance, you can access it as well with drawer.db
.
In short, you can make use of the different drawer parts like...
const { http, method, path, view, params } = drawer;
Add middleware to be run before any request to your routes in array format.
For each middleware, it is possible to pass a function or an object specifying the path and function to run.
function isLoggedIn(drawer, req, res, next) {
// Your logic
next()
}
const verifyIsAdmin = {
path: '/admin',
run(drawer, req, res, next) {
// Your logic
next()
}
}
const Website = new Spacehorn({
name: 'Awesome Website',
middleware: [
isLoggedIn,
verifyIsAdmin
],
...
Specify a database instance to be available within the drawer.
The name of the Spacehorn app. Used just for easy tracking of errors. Defaults to "Spacehorn App".
The port where the application will serve. Defaults to 3000.
The custom logger to be used. Must handle .log
, .error
, .warn
, .info
. Defaults to common console
logger.
Every HTTP request is showed on the console by default. It can be disabled with httpRequestsLog: false
.
If your application is behind a proxy, set the trust on the proxy(proxies) in array format. E.g: trustProxies: ['127.0.0.1', ...]
If there is anything else you want to have in the drawer for future use on your routes, you can add it in here.
const Website = new Spacehorn({
name: 'Awesome Website',
extendDrawer: {
anotherDB: anotherDBConnection,
someKeys: {}
}
...
On route exec:
exec(drawer, req, res) {
const { anotherDB, params } = drawer
anotherDB.query('any query')
.then()
...
}
Any Spacehorn app runs with some standard security rules by default. This can be modified to remove or add specific security features.
security: {
cors: true,
frameguard: true,
...
}
Disabled by default. To enable CORS(Cross-Origin Resource Sharing) just set 'cors: true'
Disabled by default. If you want to enable the Content-Security-Policy header set contentSecurityPolicy: true
Prefetch control is enabled by default. If you want to disable the dns prefetch control set dnsPrefetchControl: false
Disabled by default. If you want to add the X-Frame-Options header set frameguard: true
Enabled by default. If you want the X-Powered-By header set hidePoweredBy: false
Disabled by default. To set the Public-Key-Pins header add hpkp: true
Disabled by default. To set the Strict-Transport-Security header add hsts: true
Enabled by default. To disable the X-Download-Options header set ieNoOpen: false
Disabled by default. To enable the nocache
middleware, set noCache: true
Enabled by default. To disable the X-Content-Type-Options nosniff header set noSniff: false
Disabled by default. Set the Referrer-Policy: no-referrer header adding referrerPolicy: true
Enabled by default. Disable the X-XSS-Protection header with xssFilter: false