Docs menu

Node.js on Primcloud

How Primcloud detects a Node.js app, installs Node.js and your packages, runs your build scripts, and picks the default web process.

On this page

Detection#

Primcloud builds your app as Node.js when the root of your repo has a package.json.

Each app builds as one language. Some files take precedence over a package.json:

  • Python: a repo with both a requirements.txt and a package.json builds as Python, and the package.json is ignored. Don't leave another language's manifest at the root of a Node.js app.
  • Bun: a package.json with a Bun lockfile (bun.lock or bun.lockb), a bunfig.toml, a .bun-version file, or a packageManager field naming bun@… builds as a Bun app.
  • Rust: a package.json beside a Cargo.toml builds as a Rust app, with the JavaScript side built as its frontend.

The build#

  1. Node.js. The build installs the version from engines.node in package.json, or the recommended LTS if it's unset. See Runtime versions.
  2. Dependencies. It picks npm, pnpm, or Yarn and installs your dependencies from your lockfile. Without a lockfile, nothing is installed and your build scripts don't run. See Package managers.
  3. Build scripts. It runs your build script, plus heroku-prebuild and heroku-postbuild if you define them. See Customizing the build.
  4. Pruning. It prunes node_modules (npm prune, pnpm prune --prod, or Yarn's equivalent), so keep every package your app needs at runtime in dependencies.

Node.js, your package manager, and your dependencies are reused from the previous build when they haven't changed. The build log shows whether each was reused or installed.

The web process#

A Procfile decides your processes; see Formations. Without one, the web process is the first of:

  1. npm start (or pnpm start / yarn start), if package.json has a start script.
  2. node server.js, if server.js is at the root.
  3. node index.js, if index.js is at the root.

With none of these, there's nothing to run and the deploy fails. Add a Procfile, a start script, or a root server.js or index.js.

Your web process must listen on process.env.PORT (5000); no other port receives traffic. Other process types don't get a PORT.

Environment#

Your processes get your secrets as environment variables, with node and your package manager on the PATH. NODE_ENV is production unless you set it yourself. They also get WEB_CONCURRENCY and WEB_MEMORY, a suggested worker count and per-worker memory for your formation's size. Primcloud doesn't start a cluster manager for you; read them if you run one.