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:
heroku-prebuildheroku-buildif defined, otherwisebuildheroku-postbuild
{
"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 inbuild. - Work that needs
devDependencies, like code generation, can go in any of the three: they all run before pruning. - Define
heroku-buildonly when yourbuildscript 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:
[_]
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:
[_]
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:
[_]
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 withuri,suites,components,arch, andsigned_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.