Docs menu

Customizing the build

Customize the Node.js build on Primcloud: build scripts, project.toml settings, native modules, and system packages.

On this page

Most Node.js apps need no custom build steps. When yours does, use your package.json scripts, a few settings in project.toml, or system packages.

Build hooks#

The build runs these package.json scripts with your package manager, in order, skipping any you haven't defined:

  1. heroku-prebuild
  2. heroku-build if defined, otherwise build
  3. heroku-postbuild
package.json
{
  "scripts": {
    "build": "tsc && vite build",
    "heroku-postbuild": "node scripts/generate-manifest.mjs"
  }
}
  • Framework builds (next build, nuxi build, nest build) and asset bundling (Vite, esbuild, webpack) go in build.
  • Work that needs devDependencies, like code generation, can go in any of the three: they all run before pruning.
  • Define heroku-build only when your build script is for local development and shouldn't run on Primcloud.

There's no separate install step to customize: everything installs from your lockfile, so change what's installed by updating package.json and the lockfile.

Build settings#

Skip the build scripts:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.nodejs]
enabled = false

Keep everything in node_modules. After your build scripts, the build prunes node_modules with npm prune, pnpm prune --prod, or Yarn's equivalent. To skip that:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.nodejs]
actions.prune_dev_dependencies = false

Moving a package your app needs at runtime into dependencies is usually the better fix.

Native dependencies#

Packages with native code, like sharp, bcrypt, sqlite3, node-canvas, or anything built with node-gyp, install the same way they do on Linux: a prebuilt binary is downloaded, or the code is compiled during the build. The compiled code is reused while your lockfile and Node.js major stay the same.

System libraries those packages load, like libvips for sharp or libpq for a native Postgres client, come from system packages, below.

Debian packages#

When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  "libvips-dev",
  "imagemagick",
  "ffmpeg",
]

Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.

Advanced options (rarely needed):

  • Skip a package's dependencies: { name = "some-package", skip_dependencies = true }
  • Force a reinstall: { name = "some-package", force = true }
  • Install from a URL: download = ["https://example.com/package-1.2.3.deb"]
  • Add a package repository: a [[com.heroku.buildpacks.deb-packages.sources]] table with uri, suites, components, arch, and signed_by (the repository's key as an ASCII-armored PGP block).

Note

The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.