@constgen/neutrino-koa-launcher
v1.9.2
Published
Neutrino middleware for an automatic Koa application launching in a server with hot reload
Downloads
5
Maintainers
Readme
@constgen/neutrino-koa-launcher
Neutrino middleware for an automatic Koa application launching in a server with hot reload
Using this middleware your entry point should only export the Koa instance process. The server will be created automatically and will wrap your application.
src/index.js
let Koa = require('koa')
module.exports = new Koa()
.use(function ({ request, response }) {
response.body = { success: true }
})
You should not have to call new Koa().listen()
Features
- Built-in HTTP server for launching the application on development and production
- Hot Module Replacement with source-watching during development
- Disabled redundant
[HMR]
console messages - You can change your files without restarting the server
- Debug console cleared on every file change. Your outdated logs will be removed
- Automatically discovers free HTTP port to run a server locally
- Graceful server shutdown
- Outputs building log to
stdout
andstderr
. No pollution to the console - Shows PID (Process ID) in the output
- Only Linux and MacOS: Sets the NodeJS process name the same as the project name. So can be easily found with
ps x | grep myname
Requirements
- Node.js v10+
- Neutrino v9
- Webpack v4
- Koa v2.3+
Installation
@constgen/neutrino-koa-launcher
can be installed from NPM. You should install it to "dependencies"
(--save) or "devDependncies"
(--save-dev) depending on your goal.
npm install --save @constgen/neutrino-koa-launcher
Usage
In preset
Require this package and plug it into Neutrino. The following shows how you can pass an options object to the middleware, showing the defaults:
let koaLauncher = require('@constgen/neutrino-koa-launcher')
neutrino.use(koaLauncher({
port: undefined, // Set default port
http: 1, // Set HTTP version
ssl : undefined // Set SSL certificates
}))
In neutrinorc
The middleware also may be used together with another presets in Neutrino rc-file, e.g.:
.neutrinorc.js
let koaLauncher = require('@constgen/neutrino-koa-launcher')
module.exports = {
use: [
koaLauncher()
]
}
Customizing
Port
There are multiple ways to customize the HTTP port of your application server.
You can configure a default port of the server in options using server.port
property in the middleware options. For example:
koaLauncher({
port: 8080
})
Now your server will start on 8080
in both production and development modes. But this port value is considered a default value and may be overridden any time by PORT
environment variable. This may be useful for production environments as the server will check process.env.PORT
in the runtime first and then fallback to a port you have defined.
The default behavior of port when not configured is to default to 80
/443
on production and to take random free default port on development.
You can choose random free port on both production and development by passing one of these values: false
, null
, 0
. For example:
koaLauncher({
port: 0 // 0 | false | null
})
PORT
environment variable will always have a priority over any configuration.
Host
By default the server starts on a default IPv6/IPv4 host which exposes it to local network. There is no way to configure a server host from the middleware options. But you still can use HOST
environment variable to define your custom host.
HTTP version
This middleware uses HTTP v1.x by default. You can switch to HTTP v2 in options.
koaLauncher({
http: 2 // default is 1
})
SSL
You can provide paths to own SSL certificate and a public key
koaLauncher({
ssl: {
cert: path.resolve(__dirname, './ssl/ssl.cert'),
key : path.resolve(__dirname, './ssl/ssl.key')
}
})
A relative path to the project root also can be used
{
cert: './ssl/ssl.cert',
key: './ssl/ssl.key'
}
A temporary locally self-signed certificate can be configured by just passing true
koaLauncher({
ssl: true
})
Graceful Shutdown
@constgen/neutrino-koa-launcher
automatically shutdowns a server instance gracefully. Application server prints this message to signal successful closing when exited:
Server shutting down...
Server closed
During shutdown these steps are performed
- Stop listening new requests
- Close all open inactive connections
- Wait current requests to end and close their connections at the end
The middleware doesn't forcefully exit a process but waits for queued operations to finish including your async Koa middlewares. In most cases you are not required to handle it explicitly. But if you have some long running operations or timers outside Koa middlewares that continue event loop then you should take care of them by yourself. Other will be handled by @constgen/neutrino-koa-launcher
. The good practice is to use this in your code in cases of shutdown:
['SIGINT', 'SIGTERM', 'SIGBREAK', 'SIGHUP'].forEach(function (signal) {
process.once(signal, function () {
// abort all async operations
// ...
// cancel all timers
// ...
process.exitCode = 0
})
})
Don't call process.exit()
as it considered a bad practice. The application should exit naturally when there is an empty call stack and no more scheduled tasks. You should see this at the very end if the finishing of the application is correct:
Application exited
In case your application will not finish for some reason in 10 seconds, there is a timeout that kills the application forcefully. You will not be able to handle this termination. The application will exit with an error signal right after this message
Server killed, due to timeout