Skip to content

Latest commit

 

History

History
194 lines (120 loc) · 6.74 KB

readme.md

File metadata and controls

194 lines (120 loc) · 6.74 KB
Raw

glupe

What is this?

In addition to being a simple startup module for running hapi servers, glupe is also a simple hapi-based enterprise-ready project boilerplate.

There are 3 different boilerplate types:

  1. api - for api services
  2. web - for webites
  3. gov - for a gov.uk themed website

You can clone these from the glupe-base repo but the easiest way to start a new project is to use the scaffold file below. This takes care of cloning and installing dependencies for you.

Prerequisites

  • node.js 8+
  • npm
  • pm2 installed globally

Getting started

The easiest way to get started is to use the scaffold.sh file.

Using the scaffold script, let's make a web project called my-site

$ glupe-scaffold.sh web my-site

Once you have the project scaffolded, on the command line to start the server run:

npm start

This will start the server using pm2 from the entry point of the application index.js. Alternatively use node index.js if you don't want to use pm2.

Check the server is running by pointing your browser to http://localhost:3002

Project structure

Here's how to structure your project files.

  • bin (build tasks)
  • client (browser code)
  • config
    • server.json
    • schema.js
    • index.js
    • pm2.json
  • server
    • plugins
    • routes
    • views
    • manifest.js
    • index.js
  • test
  • README.md
  • index.js (startup server)

Config

Configuration files are found in the config directory. They are stored as JSON e.g. server.json. This file is excluded from the source control using a .gitignore entry.

An example file should be included in the source control though, allowing others users to understand what settings are required but avoid including any sensitive data.

Config validation

System configuration is important. They are the parameters by which your system is defined. For this reason we choose to validate all configuration files using joi.

This not only forms a source of documentation for what config settings are available, it also ensures the server will not start unless the settings are valid.

The server config validation can be found in confg/schema.js. The config can be required like any other file using const config = require('./config') (assuming the current location is the project root)

By default, the config file contains a minimum of settings:

  • Server settings (e.g. port, host)
  • The good logging configuration

To add more settings, first change the schema file, confg/schema.js, and then include the values into config/server.json

PM2

The pm2 config can be found in config/pm2.json.

This file includes the settings for running in both development mode (restarts on files changes etc.) and production.

Manifest

Glupe is used as the hapi server composer & plugin loader.

Glupe's API is a single function accepting a JSON manifest file specifying the hapi server options, connections, and registrations.

The default manifest file can be found at server/manifest.js

Plugins

hapi has a powerful plugin system and glupe's api and design encourages you to load all code in a plugin.

Server specific plugins live in the server/plugins directory.

Logging

The good plugin is used to bring a flexible logging solution to your application.

The good-file and good-console plugins are also included.

The logging configuration can be found in the config directory in the root of the application.

Views

The vison plugin is used for template rendering support.

By default, the template engine used in handlebars with support for view caching, layouts, partials and helpers.

Static files

The Inert plugin is used for static file and directory handling in hapi.js.

Routes

Incoming requests are handled by the server via routes. Each route describes an HTTP endpoint with a path, method, and other properties.

Routes are found in the server/routes directory and loaded udsing the server/plugins/router.js plugin.

Hapi supports registering routes individually or in a batch. Each route file can therefore export a single route object or an array of route objects.

A single route looks like this:

{
  method: 'GET',
  path: '/hello-world',
  options: {
    handler: (request, h) => {
      return 'hello world'
    }
  }
}

There are lots of route options, here's the documentation on hapi routes

Tasks

Build tasks are created using simple shell scripts or node.js programs. The default ones are found in the bin directory.

The task runner is simply npm using npm-scripts.

We chose to use this for simplicity but there's nothing to stop you adding gulp, grunt or another task runner if you prefer.

The common predefined tasks are:

  • npm start (Starts the server, reloads on changes if the (development pm2 config)[config.md] is used.
  • npm run build:js (Builds the browserify client-side javascript)
  • npm run build:css (Builds the client-side css)
  • npm run lint (Runs the lint task using standard.js)
  • npm run watch (Starts watching the client directory and builds the js and css on changes)

Resources

For more information around using npm-scripts as a build tool:

Testing

lab and code are used for unit testing.

See the test example/test for more information.

Linting

standard.js is used to lint both the server-side and client-side javascript code.

One Style to Rule Them All. No decisions to make. No .eslintrc, .jshintrc, or .jscsrc files to manage. It just works.

It's defined as a build task and can be run using npm run lint.