Build Status

The Nxus Core package includes the basic Application framework for building a Nxus app.

Introduction

You'll probably find the following resources useful background and help in building Nxus applcations.

Documentation

The full set of Nxus docs is available at http://docs.gonxus.org.

Installation

> npm install @nxus/core --save

Usage

In your root application, create a new Application instance:

import {Application} from '@nxus/core'

let app = new Application(options)

app.start()

export default app

Events

Nxus is built around the concept of a boot cycle. The application dispatches events in the following order:

Boot Stage Description
init indicates the application is starting up and initializing modules. Other modules are not gauranteed to be available at this phase.
load modules are initialized and loading. This is the place to do any internal setup (outside of the constructor). Other modules are not gauranteed to be available at this phase.
startup all modules have been loaded and are available. This is the place to do any setup that requires data/input from other modules (like Storage)
launch the application is launching and all services have been started. Routes are accessible. Use onceAfter('launch') to gaurantee execution after the application has completely launched

Module Loading

By defaul the Application will look for other Nxus modules in the following order:

  1. @nxus namespaced npm modules in your package.json file.
  2. Any packages that match the 'namespace-' pattern passed in the namespace application config option.
  3. folders in the ./modules folder in the root of your project
  4. any modules specified in the modules option passed into Application on instantiation.

Module Access

In order to access module commands, use the Application.get() method.

let router = Application.get('router')

Application Options

new App(...options)

Available options are:

appDir: the location to use to load the default 'package.json' file.

namespace: any additional namespaces to use to load modules in the node_modules folder. Can be a string or array of strings.

modules: an array of paths to require into the application

debug: Boolean to display debug messages, including startup banner

script: Boolean to indicate the application is a CLI script, silences all logging/output messages except for explicit console.log calls

Application Configuration

The Application exposes a core config object that contains application and module specific configuration values.

Nxus uses the rc library to provide application configuration.

The application configuration can usually be found in a .nxusrc file in the root folder.

You can override specific confirguation values using command line environment variables, which supports nesting.

nxus_myconfig__value__first=true npm start

will translate into an application config of

console.log(app.config.myconfig) // {value: {first: true}}

API

_

The Core Application class.

Application

Extends Dispatcher

Parameters
opts (Object) the configuration options
Example
import {Application} from '@nxus/core'
let app = new Application(options)
app.start()
export default app
Instance Members
get(name)
init()
boot()
stop()
start()
restart()

ConfigurationManager

src/ConfigurationManager.js

ConfigurationManager loads the internal app.config hash using the following order (each overwrites any values of the previous):

  1. Opts loaded into the application object.
  2. Opts in the config hash of the project package.json file
  3. Any environment variables
new ConfigurationManager()
Instance Members
getNodeEnv()
getEnvironmentVariables()
getConfig()

The core Dispatcher class, which implements promisified

Dispatcher

Extends EventEmitter

Example
import { Dispatcher } from '@nxus/core'
class MyClass extends Dispatcher {
  ...
}
Instance Members
once(event, [listener])
before(event, listener)
after(event, listener)
onceBefore(event, listener)
onceAfter(event, listener)
emit(event, args)

The core Module class. This provides a messaging proxy layer between modules and calling code. The main advantage of this proxy class is that missing modules won't cause exceptions in the code.

Modules are accessed through the Application.get() method

new Module()

Extends Dispatcher

Example
let router = app.get('router')

Producer modules should register themselves with the use() method, and define gather() and respond() handlers:
app.get('router').use(this).gather('route')
app.get('templater').use(this).respond('template')

Consumer modules should get the module they need to use and call provide or request
app.get('router').provide('route', ...)
app.get('templater').request('render', ...)

Modules proxy event names as methods to provide/request, so these are synomymous with above:
app.get('router').route(...)
app.get('templater').render(...)

Default implementations should be indicated by using default() to occur before provide()
Overriding another implementation can use replace() to occur after provide()
app.get('router').default('route', GET', '/', ...)
app.get('router').replace('route', GET', '/', ...)

Provide, default, and replace all return a proxy object if called with no arguments, so these are synonymous with above:
app.get('router').default().route('GET', '/', ...)
app.get('router').replace().route('GET', '/', ...)
Instance Members
use(instance)
default(name, args)
provide(name, args)
replace(name, args)
gather(name, handler)
request(name, args)
respond(name, handler)

The PluginManager handles all of the module loading. Load order is as follows:

  1. Packages in node_modules that match the passed namespace config option, and packages in the @nxus namespace.
  2. Folders in the /modules directory.
  3. Filepaths passed in the modules config option
new PluginManager()
Instance Members
loadNxusModules(options)
loadAdditionalModules(options, packages)
loadPassedPlugins(options, packages)

The Watcher class monitors the project directory and restarts the application whenever there is a change in files detected. Useful for development.

Watcher