Node.js versions and package managers

Node.js plays two roles in SrvYard. It runs Next.js and Nuxt sites as long-lived processes behind Nginx, and it builds the front-end assets (Vite, Mix, webpack) of PHP sites during a deployment. Both roles use the Node.js that SrvYard keeps on the server, so it is worth knowing where to see it, how to change it and which package manager your site uses.

This article walks through the Node.js card of the Runtimes tab, the per-site Node.js version, the package manager setting and the deploy script it feeds.

Before you begin#

• A server in the Ready state and the permission to manage runtimes on it.
• Know which major version your application supports. Check engines in package.json and the framework's documentation. Nuxt and Next.js releases usually need a recent LTS version.
• For pnpm and Yarn: a project with a lockfile (pnpm-lock.yaml or yarn.lock). For Bun: bun.lock or bun.lockb.

1. Read the Node.js card#

Open the server and choose Runtimes. The Node.js card is below the PHP card.

1. The version strip. The major versions on offer, each with its codename and support label (Maintenance LTS, Current), and the exact release for each. A tick marks the one installed on the server. SrvYard offers the majors 22, 24 and 26, and the list updates from nodejs.org when it can be reached.
2. The details of the installed version. Version (for example v22.14.0), Source (Installed by SrvYard from NodeSource, or Installed from the Ubuntu package archive, or Found on the server when you installed it yourself) and the npm version that came with it.
3. pnpm and Yarn. SrvYard does not install them as separate packages: Corepack provides them. Press Enable Corepack once, and pnpm and yarn work for every site. The Corepack line then shows Enabled.
4. Bun. Shows Not installed or the installed version. Install Bun downloads a pinned release (checked against its SHA-256 before anything is unpacked) and makes the bun command available. Install it only if you build or run something with Bun.
5. Switch to and Switch version. Choose another major and press Switch version to replace the installed one. Uninstall removes Node.js and the NodeSource repository from the server.

Switching or removing the server's Node.js does not affect sites that pin their own version. It does affect every site that uses the server default, and every deploy script that calls npm. Make the change when no deployment is running.

2. Give a site its own Node.js version#

The server's default is shown on the site's advanced settings. Open Sites > New site, choose Next.js or Nuxt, choose the server and press Advanced settings.

1. Node.js version. Server default (with the major that is installed, here Node.js 22) or a specific major. The text under the field explains the mechanism: A version of its own is installed in the site user's home with fnm, so it does not touch the Node.js other sites use. The site then runs and builds with that version only.

The Node.js sites list at the bottom of the Node.js card shows every Node site on the server, its port (server :3001) and which version it uses: Node.js 22 (own) means the site has pinned its own major.

The same dialog also holds the Root directory, website isolation and Zero downtime deployments. Next.js and Nuxt sites always deploy with zero downtime. Isolation, zero downtime and the root directory cannot be changed after the site exists.

3. Choose the package manager for builds#

For a PHP site that also builds front-end assets, open the site, choose Settings and then npm in the settings menu.

1. Frontend package manager. none, npm, pnpm, yarn or bun. SrvYard uses it to write the generated deploy script. With none, the script skips the front-end step, which suits a PHP site that has no assets.
2. Build command. Leave it empty to use the default of the chosen manager, or type your own, for example npm run build:prod. The defaults are: npm run build for npm, pnpm build for pnpm, yarn build for yarn and bun run build for bun.

Press Save under the fields. The card warns: A deploy script you edited yourself is left as it is. The setting only changes the script that SrvYard generated; if you have your own, edit the commands in it.

The install step of the generated script matches the manager and uses the lockfile strictly: npm ci, pnpm install --frozen-lockfile, yarn install --frozen-lockfile or bun install --frozen-lockfile. That is faster and reproducible, and it fails when package.json and the lockfile disagree.

4. What a Node.js site's deploy script looks like#

1. Deploy script. It first checks that npm exists, and if not stops with npm is not installed for this site. Install Node.js and the package manager from the server's Runtimes tab. Then it installs the dependencies and builds. The application's process is restarted by SrvYard once the new release is live, so the script does not need a restart line.
2. Save script stores your changes. Saving does not deploy. Press Reset to default to get the generated script back.

If the check fails, you know where to go: install Node.js on the Runtimes tab, or pick a server where it is installed. For pnpm and Yarn, enable Corepack first.

Which versions should I use?#

Choose an LTS major (labelled Maintenance LTS or Active LTS) for production: it receives security fixes for years. The Current release is fine for trying new features on a staging site, but its support ends sooner. When a major reaches its end of life, move to the next one in good time: switch a staging site first, run the build and your tests, then switch production.

Troubleshooting#

• "npm is not installed for this site". Node.js is not installed on the server, or the site's pinned version is missing. Install it from Runtimes, then deploy again.
• pnpm: command not found or yarn: command not found in a deploy. Corepack is not enabled. Press Enable Corepack on the Node.js card.
• The build fails with "unsupported engine" or a syntax error. The Node.js major is older than the project needs. Switch the server to a newer major, or pin a newer one on the site.
• A site still uses the old Node.js after I switched the server. It pins its own version (shown as own in the Node.js sites list). Change the pinned version in the site's advanced settings.
• bun: command not found. Bun is not installed. Press Install Bun on the Node.js card, then deploy again.
• Installing or switching Node.js takes long. The server downloads packages from NodeSource. Watch Recent operations at the bottom of the tab; another PHP or Node.js operation may be running first.

Related#

• Choose and switch PHP versions: the PHP side of the Runtimes tab.
• Composer and global tools: private package repositories for Composer and npm.
• Write and test a deploy script: the script that runs your build.
• Create a site on your server: choose Next.js or Nuxt when you create a site.