A lean, modern, and flexible node server
npm install node-flex-serveA lean, modern, and flexible node server
Node Flex Serve's code is widely inspired from webpack-serve.
To begin, you'll need to install node-flex-serve:
``console`
$ npm install node-flex-serve
`console
$ node-flex-serve --help
Options
--config The node-flex-serve config to serve. Alias for
--content The path from which content will be served
Default: process.cwd()
--help Show usage information and the options listed here.
--host The host the app should bind to
--http2 Instruct the server to use HTTP2
--https-cert Specify a cert to enable https. Must be paired with a key
--https-key Specify a key to enable https. Must be paired with a cert
--https-pass Specify a passphrase to enable https. Must be paired with a pfx file
--https-pfx Specify a pfx file to enable https. Must be paired with a passphrase
--log-level Limit all process console messages to a specific level and above
Levels: trace, debug, info, warn, error, silent
--log-time Instruct the logger for node-flex-serve and dependencies to display a timestamp
--no-clipboard Instructs the server not to copy the server URI to the clipboard when starting
--open Instruct the app to open in the default browser
--open-app The name of the app to open the app within, or an array
containing the app name and arguments for the app
--open-path The path with the app a browser should open to
--port The port the app should listen on
--require, -r Preload one or more modules before loading the add-ons configuration
--version Display the node-flex-serve version
Examples
$ node-flex-serve ./node-flex-serve.config.js
$ node-flex-serve --config ./node-flex-serve.config.js --port 1337
$ node-flex-serve --port 1337 # config can be omitted
`
_Note: The CLI will use your local install of node-flex-serve when available,
even when run globally._
There are a few variations for using the base CLI command, and starting
node-flex-serve:
`console`
$ node-flex-serve ./webpnode-serveack.config.js
$ node-flex-serve --config ./node-flex-serve.config.js
Those two commands are synonymous. Both instruct node-flex-serve to load the
config from the specified path. We left the flag in there because some folks
like to be verbose, so why not.
`console`
$ node-flex-serve
ConfigYou can store and define configuration / options for node-flex-serve in a numbernode-flex-serve
of different ways. This module leverages cosmiconfig,
which allows you to define options in the following ways:
- in your package.json file in a serve property.serverc
- in a or .serverc.json file, in either JSON or YML.serve.config.js
- in a file which exports a CommonJS module.
node-flex-serve supports the serve property in your config file, which
may contain any of the supported options.
When using the API directly, the main entry point is the serve function, which
is the default export of the module.
`js
const serve = require('node-flex-serve');
const config = require('./node-flex-serve.config.js');
serve({ config });
`
Returns [a Promise which resolves] an Object containing:
- close() (Function) - Closes the server and its dependencies.on(eventName, fn)
- (Function) - Binds a serve event to a function. See
Events.
#### options
Type: Object
Options for initializing and controlling the server provided.
##### addons
Please see Add-On Features.
##### context
Type: String|[String] process.cwd()
Default:
The path, or array of paths, from which static content will be served.
##### clipboard
Type: Boolean true
Default:
If true, the server will copy the server URI to the clipboard when the server is
started.
##### host
Type: String 'localhost'
Default:
Sets the host that the server will listen on. eg. '10.10.10.1'
_Note: This value must match any value specified for hot.host orhot.host.server, otherwise node-flex-serve will throw an error. Thiskoa
requirement ensures that the server and WebSocket server play nice
together._
##### http2
Type: Boolean false
Default:
If using Node v9 or greater, setting this option to true will enable HTTP2
support.
##### https
Type: Object null
Default:
Passing this option will instruct node-flex-serve to create and serve the content
through a secure server. The object should contain properties matching:
`js`
{
key: fs.readFileSync('...key'), // Private keys in PEM format.
cert: fs.readFileSync('...cert'), // Cert chains in PEM format.
pfx:
passphrase:
}
See the [Node documentation][https-opts] for more information. For SSL
Certificate generation, please read the
SSL Certificates for HTTPS section.
##### logLevel
Type: String info
Default:
Instructs node-flex-serve to output information to the console/terminal at levels
higher than the specified level. Valid levels:
`js`
[
'trace',
'debug',
'info',
'warn',
'error'
]
##### logTime
Type: Boolean false
Default:
Instruct node-flex-serve to prepend each line of log output with a [HH:mm:ss]
timestamp.
##### on
Type: Object null
Default:
While running node-flex-serve from the command line, it can sometimes be usefulObject
to subscribe to events from the module's event bus _within your config_. This
option can be used for that purpose. The option's value must be an
matching a , String: Function pattern. eg:
`js`
on: {
'listening': () => { console.log('listening'); }
}
##### open
Type: Boolean|Object false
Default:
Instruct the module to open the served bundle in a browser. Accepts an Object
that matches:
`js`
{
app:
path:
}
_Note: Using the open option will disable the clipboard option._
##### port
Type: Number 8080
Default:
The port the server should listen on.
The server created by node-flex-serve emits select events which can beObject
subscribed to. All events are emitted with a single parameter,
containing named properties for relevant data.
For example:
`js
const serve = require('node-flex-serve');
const config = require('./node-flex-serve.config.js');
serve({ config }).then((server) => {
server.on('listening', ({ server, options }) => {
console.log('happy fun time');
});
});
`
#### listening
Arguments:
Koa _server_ Object
_options_
Emitted when the server begins listening for connections.
We do recommend a path for users to generate their own SSL Certificates
safely and efficiently. That path resides in
devcert-cli; an excellent project
that automates the creation of trusted SSL certificates that will work
wonderfully with node-flex-serve.
A core tenant of node-flex-serve is to stay lean in terms of feature set, and to
empower users with familiar and easily portable patterns. This
makes the module far easier to maintain, which ultimately benefits the user.
Luckily, flexibility baked into node-flex-serve makes it a snap to add-on features.add
You can leverage this by using the option. The value of the option shouldFunction
be a matching the following signature:
`js`
add: (app, middleware, options) => {
// ...
}
- app The underlying Koa appmiddleware
- An object containing accessor functions to call bothkoa-static
the middleware.options
- - The internal options object used by node-flex-serve
Some add-on patterns may require changing the order of middleware used in the
app. For instance, if adding routes or using a separate router with the app
where routes must be added last, you'll need to call the functionsnode-flex-serve
early on. recognizes these calls and will not execute them again.node-flex-serve
If these calls were omitted, would execute both in the default,
last in line, order.
`js
add: (app, middleware, options) => {
// since we're manipulating the order of middleware added, we need to handle
// adding these two internal middleware functions.
middleware.proxy();
middleware.content();
// router must be the last middleware added
app.use(router.routes());
}
`
Listed below are some of the add-on patterns and recipes that can be found in
docs/addons`:
- bonjour
- express compress
- koa compress
- historyApiFallback
- proxy + history fallback
- proxy
- staticOptions
- useLocalIp
We welcome your contributions! Please have a read of
CONTRIBUTING.md for more information on how to get involved.
#### MIT