Configuration Management

Stored config

Config files are plain Javascript, giving you freedom to share and merge options however you like.

The config file accepts all options listed by ws --help except they should be written in "camel case". For example, the --no-conditional-get CLI option should be written noConditionalGet in the config file, --cors.allow-methods becomes corsAllowMethods etc.

The config file (lws.config.js, lws.config.mjs or lws.config.cjs by default) should look something like this:

module.exports = {
  rewrite: [
    {
      from: '/resources/(.*)',
      to: 'http://remote-api.org:8080/resources/$1'
    }
  ],
  directory: 'src',
  logFormat: 'stats'
}

An example of how you might share and merge options:

/* pull options from the env */
const remoteAPI = process.env.REMOTE_API

/* .. or an installed package */
const sharedOptions = require('shared-options')

/* merge them to taste */
const options = Object.assign({}, sharedOptions, {
  rewrite: [
    {
      from: '/resources/(.*)',
      to: `http://${remoteAPI}/resources/$1`
    }
  ]
})

module.exports = options

To inspect the active config (merged from all sources) at any point, run:

$ ws --config

To use a config file other than the default, run:

$ ws --config-file something.js

Precedence

Config is loaded and merged from three places in this order of precedence: built-in defaults, config file, command line args.

If you look at the base config without any stored config or command-line args, you'll see the built-in defaults.

$ ws --config
{
  port: 8000,
  moduleDir: [ '/Users/lloyd/Documents/lwsjs/local-web-server', '.' ],
  modulePrefix: 'lws-',
  stack: MiddlewareStack [
         BasicAuth,     BodyParser,
    RequestMonitor,            Log,
              Cors,           Json,
          Compress,        Rewrite,
         Blacklist, ConditionalGet,
              Mime,          Range,
               SPA,         Static,
             Index
  ],
  view: CliView {}
}

Create this config file, save as lws.config.js.

module.exports = {
  spa: 'index.html'
}

Now run ws again, you'll see the stored config has been merged in.

$ ws --config
{
  port: 8000,
  moduleDir: [ '/Users/lloyd/Documents/lwsjs/local-web-server', '.' ],
  modulePrefix: 'lws-',
  stack: MiddlewareStack [
         BasicAuth,     BodyParser,
    RequestMonitor,            Log,
              Cors,           Json,
          Compress,        Rewrite,
         Blacklist, ConditionalGet,
              Mime,          Range,
               SPA,         Static,
             Index
  ],
  spa: 'index.html',
  view: CliView {}
}

Options set on the command-line take precedence. Here you can see both spa (set in the config file) and port (set by the built-in defaults) have been overwritten by command line arg values.

$ ws --spa precedence.html --port 9090 --config
{
  port: 9090,
  moduleDir: [ '/Users/lloyd/Documents/lwsjs/local-web-server', '.' ],
  modulePrefix: 'lws-',
  stack: MiddlewareStack [
         BasicAuth,     BodyParser,
    RequestMonitor,            Log,
              Cors,           Json,
          Compress,        Rewrite,
         Blacklist, ConditionalGet,
              Mime,          Range,
               SPA,         Static,
             Index
  ],
  spa: 'precedence.html',
  view: CliView {}
}