Docs menu

Bun on Primcloud

How Primcloud detects a Bun app, builds it, and picks the default web process.

On this page

Detection#

Primcloud builds your app with Bun when the root of your repo has a package.json and at least one of:

  • A Bun lockfile: bun.lock or bun.lockb
  • bunfig.toml
  • .bun-version
  • A packageManager field in package.json that names Bun ("packageManager": "[email protected]")

A package.json with none of these builds as a Node.js app. Bun writes no lockfile for an app with no dependencies, so such an app needs one of the other three.

Each app builds as one language. A repo that also has a Gemfile.lock, a composer.json, or a Cargo.toml builds as a Ruby, PHP, or Rust app, with Bun building its frontend assets; see Bun as the asset builder. Don't leave another language's manifest at the root of a Bun app.

The build#

  1. Bun. The build installs the version from .bun-version, the packageManager field, or engines.bun, or the newest available version if none does. See Runtime versions. Node.js isn't installed.
  2. Dependencies. With a bun.lock or bun.lockb, it runs bun install --frozen-lockfile. Without one, the build fails unless your app has no dependencies. See Package managers.
  3. Build scripts. It runs your build script, plus heroku-prebuild and heroku-postbuild if you define them, each with bun run. See Customizing the build.
  4. Pruning. It removes your devDependencies and any package your lockfile doesn't list, so your app runs with production dependencies only. See Build settings to turn this off.

Bun and your downloaded packages are reused from the previous build when they haven't changed; the build log shows Reusing Bun or Installed Bun.

The web process#

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

  1. bun run start, if package.json has a start script.
  2. Bun running the first of server.js, index.js, server.ts, or index.ts at the root.

With none of these, there's nothing to run and the deploy fails. Add a Procfile, a start script, or one of those files. Files your build scripts generate count.

If your Procfile has no web line, the start script isn't used, but one of the root files above still becomes the web process.

Your web process must listen on process.env.PORT (5000); with Bun.serve, pass port: process.env.PORT. Other process types don't get a PORT.

Environment#

Your processes get your secrets as environment variables, with bun, bunx, and your dependencies' binaries 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; nothing starts extra processes for you.