Title: Node.js application requirements
Author: WordPress VIP Documentation
Published: May 5, 2023
Last modified: January 14, 2026

---

 1. [Node.js on VIP](https://docs.wpvip.com/node-js/)
 2. Node.js application requirements

#  Node.js application requirements

A Node.js application must fulfill several requirements before it can run successfully
on VIP’s infrastructure. The [Node.js skeleton starter repository](https://github.com/Automattic/vip-go-node-skeleton/tree/master/examples)
includes example applications that fulfill all of these requirements.

Restarts are handled automatically for production deployments and process monitors(
e.g., [nodemon](https://www.npmjs.com/package/nodemon) or [PM2](https://www.npmjs.com/package/pm2))
are not needed.

## Health check endpoint

All Node.js applications must implement [the health check endpoint](https://docs.wpvip.com/node-js/health-checks/)
using application code. The VIP Platform sends frequent health checks at this endpoint:`/
cache-healthcheck?`.

## Production dependencies

Node.js applications on the VIP Platform must [use `npm` to manage their dependencies](https://docs.wpvip.com/manage-dependencies/).
Use VIP-CLI to [manage environment variables](https://docs.wpvip.com/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:

    ```lang-shell
    npm install --production
    ```

The `build` script allows a Node.js application 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`).

    ```lang-shell
    npm run build
    ```

After a successful build, VIP will start an app using the `start` script. Not all
frameworks supply a `start` script, so Node.js applications must define one manually.

    ```lang-shell
    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):

    ```lang-js
    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`:

    ```lang-js
    "start": "frontity serve --port $PORT"
    ```

## Stateless, immutable, and multi-container

All Node.js 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. An application must not rely on absolute paths.

The file system in the container is read-only. Files can be stored temporarily in
a temp directory. Instead of hardcoding `/tmp/` to access those files, use `[os.tmpdir()](https://nodejs.org/api/os.html#ostmpdir)`.

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, [Valkey can be deployed](https://docs.wpvip.com/node-js/integrating-redis/)
alongside the Node.js application.

## URL path 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`

Avoid 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: January 14, 2026