hops-express
v15.2.1
Published
Customization for the our express server
Downloads
918
Readme
hops-express
Please see the main Hops Readme for general information and a Getting Started Guide.
This is one of the core presets for Hops and provides the development and production server configuration and mixin infrastructure in order to build a Hops application.
hops-express
strives to gracefully handle exceptions and to facilitate infrastructure integration: in case of uncaught middleware errors or upon receiving a SIGTERM
signal, the server's close
method will be called before exiting the process.
CLI
serve
This command starts an Express.js server with all middleware and configuration applied through the configureServer
hook.
Arguments
-p
/ --production
This is a shortcut for NODE_ENV=production hops serve
- it sets the environment variable NODE_ENV
to production
which enables several performance optimizations for Express.js and its middleware.
You may use either hops serve -p
or its equivalent NODE_ENV=production hops serve
.
Usage
Configuration
Preset Options
| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| https
| Boolean
| Object
| false
| no | Configure HTTPS support for Hops |
| host
| String
| [HOST]
| no | Specify the IP address that Hops should bind to |
| port
| String
| [PORT]
| no | Specify the Port that Hops should listen on |
| distDir
| String
| '<rootDir>/dist'
| no | The folder from which to serve static assets |
| gracePeriod
| number
| 30000
| no | Time to wait (in ms) until killing the server |
| helmetConfig
| Object
| {}
| no | Headers to set or overwrite in helmet |
https
Hops has built in support for HTTPS which can be configured using this setting.
You can set it to true
to enable SSL with the included self-signed certificate or you can specify an object with keyFile
and certFile
that point a proper SSL certificate.
"hops": {
"https": {
"keyFile": "./path/to/my.key",
"certFile": "./path/to/my.cert"
}
}
host
By default Hops will read an environment variable called $HOST
to find the host that the server should bind to. If $HOST
and the config host
are not defined, Hops will bind the server to the unspecified IPv6 or IPv4 address (::
or 0.0.0.0
).
"hops": {
"host": "10.10.10.10"
}
port
The port on which the server will be listening. By default Hops will try to read the environment variable $PORT
. If neither $PORT
nor the port
config are set, Hops will try to find a free port, starting at >=8080
.
"hops": {
"port": "8080"
}
distDir
This is the file-system path to where the generated assets will be written and served from.
"hops": {
"distDir": "<rootDir>/dist"
}
gracePeriod
The amount of time (in milliseconds) to wait after receiving a SIGTERM
signal or catching an unhandled middleware exception and before killing the server completely.
{
"gracePeriod": 60000
}
helmetConfig
The config to set security http headers via helmet.
Render Options
This preset has no runtime configuration options.
Mixin Hooks API
Caution: Please be aware that the mixin hooks are not part of the SemVer API contract. This means that hook methods and signatures can change even in minor releases. Therefore it's up to you to make sure that all hooks that you are using in your own mixins still adhere to the new implementation after an upgrade of a Hops packages.
configureServer(app, middleware, mode): app
(pipe) core
Use this mixin hook to register middleware or configure the Express.js Application.
It receives the following arguments:
app
This is an Express.js application instance that allows you to reconfigure the application.
middleware
This is an object whose keys are middleware phases and the values are arrays in which middleware can be pushed.
These are the phases available:
initial
- use this phase to register middleware that should be executed firstfiles
- in this phase are middleware likeexpress-static
to serve static filesparse
- this phase can be used to register middleware that parses data from incoming requests (e.g.cookie-parser
orbody-parser
)routes
- this phase registers the universal render middleware that handles all the routes in your appfinal
- this phase may be used to register error handling or other middleware that should be run last
Additionally each phase also has a pre
/ post
phase. E.g.: preinitial
or postfiles
.
mode
Describes the mode that the server is operating in, it can be one of: develop
or serve
.
const { Mixin } = require('hops-mixin');
module.exports = class MyMixin extends Mixin {
configureServer(app, middleware, mode) {
middleware.routes.push((req, res, next) => next());
if (mode === 'serve') {
middleware.preinitial.unshift((req, res, next) => next());
middleware.postfinal.push((req, res, next) => next());
}
return app;
}
};
inspectServer(app, target): app
(sequence) core
Implement this hook to get access to the listening instance of http.Server
(or https.Server
). The second argument target
will be one of develop
, serve
.
Use this hook to read the listening address or to register your application with a loadbalancer.
createServer(mode): app
(override) core
With this mixin hook it is possible to get a fully configured Express.js application instance that you can register with your own server.
It accepts develop
or serve
as mode
.
runServer(mode): void
(override) core
In case you want to programmatically start a server, you can use this mixin hook.
It accepts develop
or serve
as mode
.
Debugging
Available tags for the debug
-module are:
hops:express