Skip to main content
Open console

Node.js for builds

Node and npm for build steps, such as compiling a theme or bundling front-end assets

2 min read

Node.js and npm for build steps: compiling a theme, bundling front-end assets, running a bundler over your CSS. It is a tool the build runs in: nothing of it is started, it belongs to no machine, and it is gone by the time the release is serving.

If your site is a Node application (Next.js, Nuxt, Express), use Node.js as an application, which runs continuously and answers requests. If your site is PHP and needs npm run build during a deploy, use this one. A site can use both: a Drupal site with a themed front end serves with PHP-FPM and builds with this.

Versions

Version Status
26.13 Supported
26.11 Supported, and the default
26.12 Supported
24.21 Supported
24.22 Supported
22.23 Supported

Pin the version, not the build: name 26.11 and the platform matches it to the current build, so a security rebuild reaches you without anybody editing a repository.

What you can change

Nothing on this one. Everything it takes decides where it connects, what it is, or whether it starts — and an application able to set those could break its own environment in ways nothing here would catch.

Using it

Name it in vallic.yaml, and add image: node to the steps that need it. A step without image runs in your application's own container, and the PHP image has no node or npm:

services:
  - node: '26'

build:
  steps:
    - name: PHP dependencies
      run: composer install --no-dev --optimize-autoloader
    - name: Theme
      run: npm ci && npm run build
      image: node

The step runs against the same checkout as the others, so what it writes is in the release. npm's download cache is kept between builds. Remove what production does not need, node_modules above all, in the same step: the release is copied to every machine that runs it.

npm 12

The npm is 12, on every Node line: the image replaces the npm each line ships (11 for Node 26 and 24, 10 for Node 22). npm 12 differs in three ways:

  • A dependency's install scripts run only where your package.json allows them (allowScripts). Otherwise a package that compiles a native module or fetches a binary as it installs (bcrypt, Prisma's client, Puppeteer's browser) is installed without doing so. Run npm install-scripts approve where you develop to write the approvals, and commit them.
  • A git or URL dependency is installed only where .npmrc allows it: allow-git and allow-remote, all or root.
  • npm-shrinkwrap.json is not read. Rename it package-lock.json.

npm 11, where you choose it: run the install through npx. npx -y npm@11 ci installs with npm 11, and the rest of the step runs as it is. npx fetches it once into npm's cache, which is kept between builds.

    - name: Theme
      run: npx -y npm@11 ci && npm run build
      image: node

Next

Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works