ApostropheCMS

Appearance

Edit this page on GitHub or open an issue

@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 ​

PropertyTypeDescription
addressStringApostrophe 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.
apiKeysObjectConfigure API keys for request authentication. See the authentication guide for more.
bodyParserObjectThe json and urlencoded properties of this object are merged with Apostrophe's default options to be passed to the body-parser npm module's json and urlencoded methods.
csrfBoolean/ObjectSet to false to disable CSRF protection or to an object with a name property to customize the CSRF cookie name. See below.
expressBearerTokenObjectAn options object passed to express-bearer-token for the bearer token middleware.
portIntegerApostrophe 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.
sessionObjectProperties of the session option are used to create the session middleware. See below.
trustProxyBooleanEnables the trust proxy option for Express. 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:.
enableCacheOnDemandBooleanSet to false to disable cache on demand. See documentation.

session ​

The session options object is passed to the express-session function. If each is not otherwise specified, Apostrophe enables the following defaults:

javascript
{
  // 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:

javascript
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 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 wildcards (* and **).

You may need to use this feature when implementing POST form submissions that do not send the header.

Environment variables ​

APOS_LOG_ALL_ROUTES ​

If APOS_LOG_ALL_ROUTES is a nonempty string, Apostrophe will log the journey of each request through various middleware functions, often ending in a route. These messages appear on the server console. This is helpful when a URL does not seem to reach the intended API route.

Note that not every request ends in a route, as it is possible for middleware to redirect a request or send a response on its own.

This module's methods are used to generate the Express app. Customization should be done using the options described above. See the source code for all methods that belong to this module.

Module tasks ​

list-routes ​

Full command: node app @apostrophecms/express:list-routes

As a debugging convenience, this task command lists all routes that ApostropheCMS added to Express via the routes, apiRoutes, restApiRoutes and renderRoutes module sections. This command currently does not list routes added to Express directly via apos.app, such as the * wildcard route for pages, although these may be included in the future.