An Hapi API generator with ORM, services, job queue, authentication, caching and deployment out of the box.
- generator-hapi-api-stack
- Table of Contents
npm install -g yo
npm install -g generator-hapi-api-stack
Navigate to the directory you'd like to use for your project, then run:
yo hapi-api-stack
You will be asked a few questions to bootstrap your project.
.
├── auth
│ ├── index.js
│ └── ... // strategies
├── config
│ ├── dev.js
│ ├── staging.js
│ ├── prod.js
│ └── test.js
├── db
│ ├── index.js
│ └── indexes.js
├── jobs
│ ├── index.js
│ └── ... // jobs
├── lib
│ ├── index.js
│ └── shutdown.js
├── methods
│ ├── index.js
│ └── ... // methods
├── models
│ ├── index.js
│ └── ... // models
├── routes
│ ├── config
│ ├── handlers
│ ├── validations
│ ├── index.js
│ └── ... // routes
├── runtime
│ ├── index.js
│ ├── cache.js
│ ├── jobs.js
│ └── routes.js
├── services
│ ├── index.js
│ └── ... // services
├── test
├── server.js
├── config.js
├── shipitfile.js
├── process.json
└── README.md
The auth
folder exports a plugin that registers all defined authentication strategies.
Use the Auth Generator or do it manually by creating a file in the auth
folder
The config
folder holds environment specific configuration that will be loaded at server startup: you can later access the config object for the chosen environment by either referencing server.settings.app
(if you have server
in scope) or by requiring config.js
directly.
Create a config/envName.js
file:
// config/envName.js
module.exports = {
env: 'envName', // must match filename
// ...
};
Add the environment in config.js
:
// config.js
const env = require('get-env')({
staging: 'staging',
test: 'test',
envName: 'envName'
});
Check out node-get-env if you need further customization.
You can set up and use multiple cache providers:
// config/envName.js
module.exports = {
...
cache: {
cacheName: {
engine: 'catbox-redis',
name: 'cacheName',
host: '0.0.0.0',
port: 6379,
partition: 'my-api'
},
someOtherCache: { ... }
},
// ...
};
Where cacheName
and someOtherCache
must be valid Catbox client objects.
You can then access cacheName
by either referencing server.settings.app.cache.cacheName
(if you have server
in scope) or by directly requiring config.js
.
If you want to disable caching for a specific environment, remove the cache
property or set it to a falsy value.
With Waterline you can have multiple database connections, just make sure you are requiring all the adapters you are using:
// config/envName.js
module.exports = {
...
dogwater: {
connections: {
mysqlConnection: {
adapter: 'sails-mysql',
host: 'localhost',
port: 3306,
user: 'user',
password: 'password',
database: 'mydb'
},
mongoConnection: {
adapter: 'sails-mongo',
host: 'localhost',
port: 27017,
database: 'mydb'
}
},
adapters: {
'sails-mysql': require('sails-mysql'),
'sails-mongo': require('sails-mongo')
}
}
};
You can prefix all your routes:
module.exports = {
...
apiPrefix: '/api/v1',
// apiPrefix: '' <- no prefix
};
The db
folder exports a plugin that perform database related initialization.
The template you'll get with the generator has a db/indexes.js
file where you can set up database indexes.
// db/indexes.js
module.exports = {
// modelName must be an existing Waterline model
modelName: [
// indexes ...
]
};
The jobs
folder exports a plugin that does three things:
- Registers all jobs in the
jobs
folder - Starts all recurring jobs
- Expose the Agenda instance on the server so that you can later reference
server.jobs
If you want to disable jobs for a specific environment, remove the jobs
property in config/envname.js
or set it to a falsy value.
There are basically two types of job you can set up:
- Manual: you define it, and then its execution must be triggered manually
- Recurring: you define it, and it will keep running as long as the server is up
Use the Job Generator or do it manually by creating a file in the jobs
folder
The lib
folder registers all the plugins, so if you want to take something out or load more plugins just modify lib/index.js
as you see fit.
Server shutdown cleanup is in lib/shutdown.js
The methods
folder exports a plugin that registers server methods.
The models
folder contains all the Waterline models to be loaded through the Dogwater plugin
Use the Model Generator or do it manually by creating a file in the models
folder
The routes
folder exports a plugin that registers routes on the server.
The following convention is used:
routes/domain.js
exports an array of route configuration objects
routes/config/domain.js
is where each route gets its specific options
routes/handlers/domain.js
exports the route handlers used in the config file
routes/validations/domain.js
exports the validation objects used in the config file
Use the Route Generator or do it manually by creating a file in the routes
folder
The runtime
folder exports a plugin that registers runtime configuration objects under server.plugins.runtime
.
The exported content of runtime/filename.js
will be available under server.plugins.runtime.filename
.
runtime/cache.js
holds server cache options
runtime/routes.js
holds routes domain-specific options
runtime/jobs.js
holds Agenda jobs options
You can add as many runtime config files as you want and they will be automatically loaded at startup.
The services
folder exports a plugin that registers Seneca services through the Chairo plugin
Use the Service Generator or do it manually by creating a file in the services
folder
The template project uses the Labbable plugin for testing purposes.
This will get you a fully initialized server ready to be tested.
The template you will get comes with a shipitfile.js
: check out the Shipit project to understand how to customize for your own needs.
From the root of your project, run:
yo hapi-api-stack:auth
It will create a new file, with the name you specified, in /auth
.
From the root of your project, run:
yo hapi-api-stack:job
It will create a new file, with the name you specified, in /jobs
.
Don't forget to add the newly created job configuration in runtime/jobs.js
.
Each job should have: NAME
, TYPE
and an optional CONFIG
property.
Recurring jobs require, in addition, a FREQUENCY
property.
Refer to runtime/jobs.js
template file to check how to set up a job.
From the root of your project, run:
yo hapi-api-stack:model
It will create a new file, with the name you specified, in /models
.
Please note that the ORM database connection to use for the model should exist or you'll get an error on server startup.
From the root of your project, run:
yo hapi-api-stack:route
It will create four files with the name you specified in /routes
, /routes/config
, /routes/handlers
, /routes/validations
and, if specified, a file in /test
.
From the root of your project, run:
yo hapi-api-stack:service
It will create a new file, with the name you specified, in /services
.
MIT Public License.