trailpack

trailpack

Trailpack Interface. Trailpacks extend the capability of the Trails framework. (Application functionality should be extended using Services).

Usage

This class should be extended by all trailpacks. Override the trailpack API methods.

const Trailpack = require('trailpack')

class ExampleTrailpack extends Trailpack {

  /**
   * Configure the lifecycle of this trailpacks.
   */
  get lifecycle () {
    return {
      initialize: {

        /**
         * Only initialize this trailpack after trailpack-router has been
         * initialized.
         */
        listen: [ 'trailpack:router:initialize' ]
      }
    }
  }

  validate () {
    if (!this.app.config.example) throw new Error('config.example not set!')
  }

  configure () {
    this.app.config.example.happy = true
  }

  initialize () {
    this.interval = setInterval(() => {
      this.log.debug('happy?', this.app.config.example.happy)
    }, 1000)
  }

  unload () {
    clearInterval(this.interval)
  }

  constructor (app) {
    super(app, {
      config: require('./config'),
      api: require('./api'),
      pkg: require('./package')
    })
  }

}

API

Boot Lifecycle

1. trails:start (event)
2. validate()
3. configure()
4. initialize()
5. trails:ready

Properties

log

Provides convenient access to the Trails logger. (e.g. this.log.debug('hello'))

packs

Access the application's loaded Trailpacks. This is a mapping of name -> Trailpack. (e.g. this.packs.core)

on, once, emit, after

Emit/Listen for events on the Trails EventEmitter. Convenience methods for this.app.on, this.app.once, etc. (e.g. this.emit('custom:event'))

Methods

constructor(app, definition)

Instantiate the Trailpack. definition is an object which contains three optional properties: config, api, pkg. Trailpack configuration is merged into the application configuration.

validate()

Validate the preconditions for proper functioning of this trailpack. For example, if this trailpack requires that a database is configured in config/database.js, this method should validate this. This method should incur no side-effects. Do not alter any extant configuration.

configure()

Alter/Extend the configuration (app.config) of the application, or add new sections to the config object for the trailpack. This method is run before the application is loaded -- after validate, and before initialize. Trails does not allow further configuration changes after this lifecycle stage is complete.

initialize()

If you need to bind any event listeners, start servers, connect to databases, all of that should be done in initialize. The app's configuration is guaranteed to be loaded and finalized before this stage.

unload()

Cleaup any resources/daemons started by this Trailpack. Used by trailpack-autoreload and other system tools to cleanly release resources in order to shutdown/restart the Trails application.

Types

The trailpack type is used to distinguish between Trailpacks by the role they perform in the application. It is also used by developer tools such as Trailmix

system

These trailpacks provide critical framework-level functionality that most/all other trailpacks will depend on, such as core and router.

const SystemTrailpack = require('trailpack/system')

module.exports = class HapiTrailpack extends SystemTrailpack {

}

server

These allow you to use various node.js web server frameworks with Trails, such as express, hapi, and koa. Typically, only one server pack will be installed in a Trails Application.

const ServerTrailpack = require('trailpack/server')

module.exports = class HapiTrailpack extends ServerTrailpack {

}

datastore

Datastore trailpacks provide a unified way to configure various persistence stores. These may be ORMs, query builders, or database drives. Examples include knex, graphql and waterline. Typically, only one datastore pack will be installed in a Trails Application.

const DatastoreTrailpack = require('trailpack/datastore')

module.exports = class KnexTrailpack extends DatastoreTrailpack {

}

tool

Every application needs a suite of tools for development, debugging, monitoring, etc. These trailpacks integrate various modules with Trails to provide a richer developer experience. Some tool packs include autoreload, webpack, repl. Trails Application logic will typically not rely on these trailpacks directly.

const ToolTrailpack = require('trailpack/tool')

module.exports = class WebpackTrailpack extends ToolTrailpack {

}

extension

Extension packs exist to augment, or extend, the functionality of other trailpacks or existing framework logic. For example, footprints provides a standard interface between server and datastore trailpacks. realtime adds additional functionality to a server. sails lets you plugin an entire sails project directly into a Trails Application. bootstrap extends the Trails boot process so that a custom method can be run during application startup.

const ExtensionTrailpack = require('trailpack/extension')

module.exports = class FootprintsTrailpack extends ExtensionTrailpack {

}

misc

All trailpacks that don't fit previous types.

const Trailpack = require('trailpack')

module.exports = class ExampleTrailpack extends Trailpack {

}

Documentation

• Trailpack Implementation Guide
• API Reference

Contributing

We love contributions! Please see our Contribution Guide for more information.

License

MIT