Using Node.js and NPM with the DeployHQ Build Pipeline

Many web projects rely on Node.js for compiling assets, bundling JavaScript, and managing dependencies. Whether you're building a React frontend, processing Tailwind CSS, or running a full-stack application, your deployment workflow needs a build step before files reach your server.

DeployHQ's build pipeline lets you run Node.js commands in an isolated environment before deployment. Dependencies are installed, assets are compiled, and only the resulting files are uploaded to your server.

How the build pipeline works with Node.js

When you add build commands to your DeployHQ project, they run on DeployHQ's build servers — not on your production server. This means you can use Node.js tooling even when deploying to environments that don't have Node installed, such as S3 buckets or Shopify themes.

The build process runs after your code is pulled from the repository and before files are transferred to the server. DeployHQ tracks which files changed between builds, so only modified files are uploaded.

Setting up NPM build commands

When creating a build command, select the NPM option for the most common preset:

npm install --quiet
npm run build

You can customise these commands for your project. For example, a Next.js static export might use:

npm ci
npm run build
npm run export

Or a Vite-based project:

npm ci
npx vite build

If your project uses a different build script name, adjust the commands to match what's in your package.json.

Using alternative package managers

While NPM is the default, DeployHQ's build environment supports other Node.js package managers.

pnpm

pnpm uses a content-addressable store to avoid duplicating packages across projects, resulting in faster installs and less disk usage:

corepack enable
pnpm install --frozen-lockfile
pnpm run build

Cache node_modules and .pnpm-store in your build configuration to speed up subsequent deployments.

Yarn

Yarn is another popular alternative, especially in projects that use workspaces:

corepack enable
yarn install --frozen-lockfile
yarn build

Bun

Bun is a fast JavaScript runtime and package manager. If your project is compatible with Bun, you can use it for significantly faster install and build times:

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun install
bun run build

Configuring Node.js versions

By default, DeployHQ uses the latest supported Node.js version. If your project requires a specific version (for example, Node 20 LTS or Node 22 LTS), you can configure this under Build Pipeline → Build Configuration.

This is important for projects that depend on specific Node.js APIs or have peer dependency requirements tied to a particular version.

Caching node_modules for faster builds

Installing dependencies with npm install or pnpm install can take significant time, especially for large projects. DeployHQ's build cache keeps a copy of your dependencies between deployments.

Under Build Pipeline → Build Configuration → Cached Build Files, add:

node_modules
node_modules/**

For pnpm, also add:

.pnpm-store
.pnpm-store/**

On subsequent deployments, cached dependencies are restored before your build commands run. Only new or updated packages are downloaded, cutting build times significantly.

Excluding build artefacts from uploads

Files generated during the build process that aren't needed on your server — like node_modules — should be excluded from the deployment. Under Settings → Excluded Files, add:

node_modules
node_modules/**

This ensures your dependency directory isn't uploaded alongside your compiled assets. The build pipeline compiles everything locally, and DeployHQ uploads only the output.

Common frameworks and their build commands

Here are typical build configurations for popular frameworks:

For framework-specific guides, check our guides library which covers detailed setup instructions for each.

Working with monorepos and workspaces

If your project uses npm workspaces, pnpm workspaces, or a monorepo tool like Turborepo, your build commands may need to target a specific workspace:

npm ci
npm run build --workspace=packages/frontend

Or with pnpm:

corepack enable
pnpm install --frozen-lockfile
pnpm --filter frontend build

Make sure your excluded files and cached build files account for the monorepo structure.

Using ESM and modern JavaScript

If your project uses ES Modules ("type": "module" in package.json), no special configuration is needed in DeployHQ's build pipeline. The Node.js version configured in your build settings determines ESM support — Node 18+ has full ESM support enabled by default.

For projects transitioning from CommonJS to ESM, ensure your build tooling (Webpack, Vite, Rollup, etc.) is configured to output the format your server expects.

Ready to automate your Node.js builds? Sign up for DeployHQ and configure your build pipeline in minutes.

If you have any questions about using Node.js with DeployHQ, contact us at support@deployhq.com or reach out on X (Twitter).