# @apostrophecms/express
Extends: @apostrophecms/module
âšī¸
This module initializes the Express framework, which Apostrophe uses and extends to implement both API routes and page-serving routes. The Express app
object is made available as apos.app
, and the express
object itself as apos.express
. This module also adds a number of standard middleware functions and implements the server side of CSRF protection for Apostrophe.
# Options
Property | Type | Description |
---|---|---|
address | String | Apostrophe listens for connections on all interfaces (0.0.0.0 ) unless this option is set to another address. If the ADDRESS environment variable is set, it is used instead. |
apiKeys | Object | Configure API keys for request authentication. See the authentication guide for more. |
bodyParser | Object | The json and urlencoded properties of this object are merged with Apostrophe's default options to be passed to the body-parser npm module's (opens new window) json and urlencoded methods. |
csrf | Boolean/Object | Set to false to disable CSRF protection or to an object with a name property to customize the CSRF cookie name. See below. |
expressBearerToken | Object | An options object passed to express-bearer-token (opens new window) for the bearer token middleware. |
port | Integer | Apostrophe listens for connections on port 3000 unless this option is set to another port. If the PORT environment variable is set, it is used instead. |
session | Object | Properties of the session option are used to create the session middleware. See below. |
trustProxy | Boolean | Enables the trust proxy option for Express (opens new window). Set to true to tell the Express app to respect X-Forwarded-* headers. This is helpful when Apostrophe is generating http: URLs even though a proxy like nginx is being used to serve it over https: . |
enableCacheOnDemand | Boolean | Set to false to disable cache on demand. See documentation. |
# session
The session
options object is passed to the
express-session (opens new window) function. If each is not otherwise specified, Apostrophe enables the following defaults:
{
// Does not save sessions until something is stored in them. This greatly
// reduces `aposSessions` collection size.
saveUninitialized: false,
// We are using the 3.x mongo store which is compatible with the
// `resave: false` option, preventing the vast majority of session-related
// race conditions.
resave: false,
// Always update the cookie, so that each successive access revives your
// login session timeout.
rolling: true,
// This option should be customized in every project.
secret: 'you should have a secret',
name: self.apos.shortName + '.sid',
cookie: {}
}
By default Apostrophe stores sessions in MongoDB so it is not necessary to install another solution. If you want to use another session store, you can pass an instance as the store sub-option, but it's easier to let Apostrophe do the work of setting it up:
module.exports = {
options: {
session: {
store: {
name: 'connect-redis',
options: {
// redis-specific options here
}
}
}
}
}
Be sure to install connect-redis
, or the store of your choice, as an npm dependency of your project.
# csrf
By default, Apostrophe implements CSRF protection (opens new window) via an XSRF-TOKEN
cookie. All non-safe HTTP requests (not GET
, HEAD
, OPTIONS
or TRACE
) automatically receive protection via CSRF middleware, which rejects requests in which the CSRF token does not match the header. If the request was made with a valid API key or bearer token it bypasses this check.
If the csrf
option is set to false
, CSRF protection is disabled. This is not recommended. Set this option to an object with a name
property to set that property's value as the CSRF cookie name.
You can configure exceptions to CSRF protection by setting the csrfExceptions
option of any module to an array of route names specific to that module, or URLs (starting with /
). Exceptions may use Minimatch (opens new window) wildcards (*
and **
).
You may need to use this feature when implementing POST
form submissions that do not send the header.
# Related documentation
# Featured methods
This module's methods are used to generate the Express app. Customization should be done using the options described above. See the source code (opens new window) for all methods that belong to this module.