---
title: Configuring Builds
description: Learn how to configure builds on the WP Engine Headless Platform
url: https://developers.wpengine.com/docs/headless-platform/platform-guides/customizing-builds/
image: https://developers.wpengine.com/og/docs/headless-platform/platform-guides/customizing-builds.png
---

# Configuring Builds

This guide describes how to configure the Headless Platform build system for your applications.

## Setting a custom version of Node.js, npm and Yarn

### Node.js

#### Supported Node Versions

New LTS Node.js versions become available for use within one month of the ‘Initial Release’ and become the default version within one month of the ‘Active LTS Start.’ The Headless Platform drops support for Node.js versions six months after their upstream end-of-life date. Please consult [Node.js release dates](https://nodejs.org/en/about/previous-releases) as needed.

| Node.js Version | Status          | Node.js EOL | Platform Support Start | Platform End of Support |
| --------------- | --------------- | ----------- | ---------------------- | ----------------------- |
| 18 (Hydrogen)   | EOL             | April 2025  | May 2022               | August 2026             |
| 20 (Iron)       | EOL             | April 2026  | May 2023               | October 2026            |
| 22 (Jod)        | Maintenance LTS | April 2027  | May 2024               | October 2027            |
| 24 (Krypton)    | Active LTS      | April 2028  | June 2025              | October 2028            |
| 26 (Lithium)    | Current         | April 2029  | June 2026              | October 2029            |
| 28 (Magnesium)  | Planned         | April 2030  | May 2027               | October 2030            |

> **Danger**
>
> Using a version of Node.js that has reached end-of-life may lead to [security vulnerabilities](https://nodejs.org/en/about/eol) and is not recommended. The Headless Platform will stop supporting EOL versions of Node.js six months after their upstream EOL date, but it is recommended to update to a supported version as soon as possible.

#### Setting a Custom Node.js Version

If your `package.json` file does not specify a Node.js version, the Headless Platform defaults to using the `Active LTS` to build your applications.

To set a custom version of Node.js, use the [engines field](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#engines) in the `package.json` file. For example, here is how to deploy your application using Node.js 24:

```json
"engines": {
  "node": ">=24.0.0 <25.0.0"
},
```

Headless Platform builds use [Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning) to specify the Node.js version. This can be used to specify a specific versions, a range of versions, or a major version. If a range is used, ensure that an upper bound is set (e.g. <19.0.0) as the build may use the new node version unexpectedly. For example, a clean rebuild will clear the cached version of Node.js.

The version of Node.js in use on your builds can be found in the build output:

```
Node.js Setup:
  Detecting Node.js version
    Searching for the Node.js version in package.json => engines
    Using Node.js ">=24.0.0 <25.0.0" from the package.json engines field


  Installing Node.js
  nodejs: Contributing to layer
    Node.js v24.15.0 installed because it is the latest version that matches the constraint ">=24.0.0 <25.0.0"
```

To see what version of Node.js you are using on your local machine use the following command:

Terminal window

```bash
$ node --version
v24.15.0
```

### npm

The builds use the default version of npm that comes with the Node.js release selected. You can use [this page](https://nodejs.org/en/download/releases/) to search which version of npm comes with a particular version of Node.js.

You can set a custom version of npm used in Headless Platform builds in two places. The first is the `engines` field in the `package.json` file. Similar to Node.js versions above, our Headless Platform uses semver to specify the version used. Here is how to set it to use the latest version of npm v8:

```json
"engines": {
  "npm": "8"
}
```

An alternative way to set npm is to use the `packageManager` field in the `package.json` file. Note the difference in format compared to the `engines` field above where the version must be an exact version of npm:

```json
"packageManager": "npm@8.11.0"
```

The version of npm being used on your builds can be found in the build output:

```
npm Setup:
  Detecting npm version
    Searching for the npm version in:
     1. package.json => engines
     2. package.json => packageManager
    Using npm "8" from package.json engines field


  Installing npm
    npm: Contributing to layer
      npm v8.13.2 installed because it is the latest version that matches the constraint "8"
```

To see what version you have installed locally use:

Terminal window

```bash
$ npm --version
8.11.0
```

### Yarn

If the `yarn.lock` file is committed then yarn is used to build your application. Currently only Yarn Classic (v1) is supported on Headless Platform builds.

If you want to set an exact version of Yarn use the `packageManager` field in `package.json`:

```json
"packageManager": "yarn@1.22.16"
```

The version of Yarn being used on your builds can be found in the build output:

```
Yarn Setup:
  Determining yarn version
  Yarn v1.22.16 installed
```

Use this command to see what version you are using locally:

Terminal window

```bash
$ yarn --version
1.22.16
```

### pnpm

If the `pnpm-lock.yaml` file is committed, pnpm is used to build your application.

If you want to set an exact version of pnpm, use the `packageManager` field in `package.json`:

```json
"packageManager": "pnpm@9.2.0"
```

The version of pnpm being used on your builds can be found in the build output:

```
pnpm Setup:
  Detecting pnpm version
    pnpm v9.2.0 installed
```

Use this command to see what version you are using locally:

Terminal window

```bash
$ pnpm --version
9.2.0
```

## Installing Dependencies

It is recommended to commit your `package-lock.json` file to version control. Once committed, the Headless Platform uses the lock file to run `npm ci` to install package dependencies which builds your app with the same dependencies used in your local dev environment.

If the `package-lock.json` file is not present then `npm install` is run.

## Custom Build Commands

This is the command which is run to build your application. Custom build commands can be set on our Headless Platform and per environment.

The build command can be configured 3 ways. In order of priority they are:

1. `HEADLESS_BUILD_SCRIPT` - Builds look for the `HEADLESS_BUILD_SCRIPT` environment variable. For example, `HEADLESS_BUILD_SCRIPT=my-build` means `npm run my-build` will be run if using npm
2. `wpe-build` - if it exists in `package.json` then `npm run wpe-build` is run if using npm
3. `build` - if it exists in `package.json`

Below is an example of how to set each build command:

```json
"scripts": {
    "my-build": "next build",  // only run if HEADLESS_BUILD_SCRIPT is set
    "wpe-build": "next build",
    "build": "next build",
},
```

## Custom Start Commands

The start command is run to start your Node application once it is deployed. By default the Headless Platform runs the `start` script in `package.json`. This can be overridden by setting the `HEADLESS_START_SCRIPT` environment variable. For example, `HEADLESS_START_SCRIPT=start-dev` means `next dev` will be run instead of `next start` with the package.json below:

```json
"scripts": {
    "start": "next start",
    "start-dev": "next dev",
},
```

## Framework Build Assets Cache

Our Headless Platform caches common framework assets between builds to optimize build times.

The folders that are cached currently are:

- `.cache`
- `.next/cache`
- `.nuxt`
- `.wordpress-cache`
- `public`

If any of the above folders are in the projects root directory at the start of the build, the build will **not** override them.

Performing a clean rebuild, either through a webhook or through User Portal, will remove any previously cached files. For instructions on how to [perform a clean rebuild](https://developers.wpengine.com/docs/headless-platform/platform-guides/troubleshooting-builds#clean-rebuild-and-clear-domain-cache) you can reference the guide on troubleshooting builds.

## Rebuild an Environment via Webhook

This content has moved to [a standalone guide](https://developers.wpengine.com/docs/headless-platform/platform-guides/webhooks). Please reference that guide to configure your webhooks.

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```