Skip to content

Node.js on VIP

The VIP Platform supports two types of Node.js applications.

  • Decoupled/headless frontend: The REST API allows WordPress to operate in a decoupled/headless manner. Rather than a traditional PHP-driven theme, sites can run as a static single-page application (SPA) or a fully isomorphic application (with server-side rendering). Both types are supported, and VIP offers add-ons (like Redis) to make them even more complete.
  • Microservices/APIs: WordPress is flexible enough to support many different use cases, but not all of them. A companion microservice can offload tasks that may not be well-suited for a typical WordPress app, such as a proxy for another API or service or a middleware layer like a GraphQL API.

To enable New Relic for a Node.js environment, open a VIP Support request and install the New Relic NPM package in the Node.js application.

Requirements

An application must fulfill several requirements before it can run on VIP’s infrastructure.

Exposing a health check endpoint

The VIP Platform sends frequent health checks at this endpoint: /cache-healthcheck?. All Node.js applications must implement the health check endpoint using application code.

Production dependencies

Node.js applications on the VIP Platform must use npm to manage their dependencies. Use VIP-CLI to manage environment variables that need to be present when building and running the application.

VIP uses the dependencies and scripts defined in package.json to install, build, and start an application. Make sure all necessary packages needed for an application to run are publicly accessible and are added as dependencies and not devDependencies.

Only production dependencies are installed:

npm install --production

The build script allows an app to be compiled or perform any necessary tasks before being started. Even if an app does not require a build step, it is still expected that this script to be present. Use "build": "echo 'No build'" or equivalent to fulfill this requirement. The build script must complete successfully (exit with 0).

npm run build

After a successful build, VIP will start an app using the start script. Not all frameworks supply a start script, so an app may need to define one manually.

npm start

Dynamic PORT

VIP assigns a dynamic port to applications using the PORT environment variable. An application needs to start on the assigned port to work correctly.

If an application’s port is declared in code, use process.env.PORT to access the assigned port. Add logic to fall back to a default port if no port is assigned (i.e., in local development):

const PORT = process.env.PORT || 3000;

If an application’s port is defined in the start script in package.json, access the assigned port using $PORT:

"start": "frontity serve --port $PORT"

Stateless, immutable, and multi-container

All applications on VIP must be able to run across multiple containers and processes simultaneously. This means that each deployment of a Node.js application must be stateless and immutable. The file system in the container is read-only, and an application must not rely on absolute paths. If any data is stored in memory, it will be lost on deployment or when containers are added or removed.

Data can be persisted elsewhere (e.g., in a WordPress application via the REST API or GraphQL). If cache data is needed for later reuse, Redis can be deployed alongside the Node.js application.

No process monitors

For production deployment, an application does not need process monitors (like nodemon or PM2) to handle restarts. This is handled automatically.

The Node.js skeleton starter repository includes example applications that fulfill all the above requirements.

Limitations

For security and performance reasons, some paths have special behavior across all applications hosted on VIP, even Node.js applications:

  • /wp-admin
  • /wp-content
  • /wp-includes
  • /wp-login

VIP recommends avoiding the use of these paths on Node.js sites. If one of these paths is needed to proxy or redirect a request matching a WordPress site, it should be rewritten. For example, redirect https://nodejs-app.example.com/admin to https://wp-app.example.com/wp-admin/.

Last updated: February 13, 2023