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
By default, our Headless Platform uses the latest v20 LTS release of Node.js. The platform current supports Node.js v18, v20 and v22.
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.’ Please consult Node.js release dates as needed.
⚠️ Important: If your package.json
file does not specify a Node.js version, the Headless Platform defaults to using Node.js v20 to build your applications.
To set a custom version of Node.js, use the engines field in the package.json
file. For example, here is how to deploy your application using Node.js 18:
"engines": {
"node": ">=18.0.0 <19.0.0"
},
Note: Headless Platform builds use 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 ">=18.0.0 <19.0.0" from the package.json engines field
Installing Node.js
nodejs: Contributing to layer
Node.js v18.15.0 installed because it is the latest version that matches the constraint ">=18.0.0 <19.0.0"
To see what version of Node.js you are using on your local machine use the following command:
$ node --version
v18.15.0
npm
The builds use the default version of npm that comes with the Node.js release selected. You can use this page 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:
"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:
"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:
$ 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
:
"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:
$ 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
:
"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:
$ 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:
HEADLESS_BUILD_SCRIPT
- Builds look for theHEADLESS_BUILD_SCRIPT
environment variable. For example,HEADLESS_BUILD_SCRIPT=my-build
meansnpm run my-build
will be run if using npmwpe-build
- if it exists inpackage.json
thennpm run wpe-build
is run if using npmbuild
- if it exists inpackage.json
Below is an example of how to set each build command:
"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:
"scripts": {
"start": "next start",
"start-dev": "next dev",
},
Framework Build Assets Cache
Our Headless Platform caches common framework assets between builds to optimise 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 you can reference the guide on troubleshooting builds.
Rebuild an Environment via Webhook
This content has moved to a standalone guide. Please reference that guide to configure your webhooks.