An Hapi API generator with ORM, services, job queue, authentication, caching and deployment out of the box.

• generator-hapi-api-stack
• Table of Contents
  • Installation
  • Project Generator
  • Project Structure
    • auth
      • Adding a new auth strategy
    • config
      • Adding a new environment
      • Adding a cache provider
      • Adding a database connection
      • API route prefix
    • db
    • jobs
      • Job types
      • Adding a new job
    • lib
    • methods
    • models
      • Adding a new model
    • routes
      • Adding a new route
    • runtime
    • services
      • Adding a new service
  • Testing
  • Deployment
    • shipitfile.js
    • process.json
  • Generators
    • Auth Generator
    • Job Generator
    • Model Generator
    • Route Generator
    • Service Generator
  • License

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.

pm2 docs

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.