Skip to content

Backgrounds

How-to Guides

Technical References

VIP Platform /

Node.js Applications on VIP

Note

We currently recommend hosting WordPress components with VIP, and your Node.js application externally. This document is for pre-existing clients.

Use cases of Node.js applications

We currently support two types of Node.js applications on VIP.

Decoupled / headless frontend

The REST API allows WordPress to operate in a decoupled / headless manner. Rather than a traditional PHP-driven theme, sites can be run as a static single-page application (SPA) or a fully isomorphic application (with server-side rendering).

Both types are supported, and we offer some add-ons (like Redis and MariaDB) 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 be used to 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.

Requirements

Requirement 1: Exposing a health route

In order to know the health of your Node app, we keep sending health requests (pings) to a specific route called /cache-healthcheck. If your app doesn’t respond to those requests, our monitoring system will flag it as down and keep restarting it indefinitely.

Our first requirement is for your app to expose this route and responds with HTTP status 200. Here’s how you can implement it in the most used frameworks:

Usage with Express:

const app = express();

app.get('/cache-healthcheck', function (req, res) {
  res.sendStatus( 200 );
})

Usage with Next.js:

There are two steps to implement this in Next.js. First add the following file pages/api/cache-healthcheck.js with the following content:

export default function handler(req, res) {
	res.status(200).send('Ok');
}

Then in your next.config.js, add the following rewrite:

module.exports = {
  async rewrites() {
    return [
      {
        source: '/cache-healthcheck',
				destination: '/api/cache-healthcheck',
      },
    ]
  },
}

This will make it possible for the app to redirect all requests hitting /cache-healthcheck to /api/cache-healthcheck and respond with 200 .

Requirement 2: Dynamic PORT

In VIP, we automatically assign ports to apps using the PORT environment variable. In order for your app to work correctly, it needs to start on the assigned port.

The following code will make your app start on the assigned port but fall to port 3000 if no port is assigned (like in local development):

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

Requirement 3: NPM required scripts

For all Node apps, we have a few required npm scripts that we expect to be present in your package.json:

$ npm install --production

Make sure all necessary packages needed for your app to run are added as dependencies and not devDependencies as we don’t install those before starting your app. Only production dependencies are installed.

$ npm build

This is the step where you can build your app or run any things you want before starting it. If your app does not need a build step, we still expect this script to be present. Please use "build": "echo Build not needed" or equivalent to fill this requirement.

$ npm start

After the build step, we will start your app using the start script. Some frameworks like create-react-app use the serve script instead of start, so you may need to adjust this before pushing your code to production.

Other requirements

Stateless and multi-container

All applications on VIP must be able to run across multiple containers and processes at the same time. This means that the app must largely be stateless. If any data is stored in memory it will be lost on deployment or if containers are added/removed. If you want your data to be persisted, you can use our MariaDB add-on for your database. If you need a caching layer, we also offer Redis.

No process monitors

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

An example of all these requirements in action can be found on our Node skeleton starter repository.

Last updated: May 21, 2021