Docs menu

Package managers

How Bun installs dependencies on Primcloud: lockfile requirements, frozen installs, private registries, and Bun as the asset builder for Ruby, PHP, and Rust apps.

On this page

Bun is its own package manager: a Bun app installs with the same Bun that runs it. Both bun.lock and the older bun.lockb work. An app using npm, pnpm, or Yarn is a Node.js app; see Node.js package managers.

Install behavior#

With a lockfile, the build runs bun install --frozen-lockfile, which installs exactly what the lockfile records and fails if it doesn't match package.json.

Without a lockfile, the build runs bun install and expects nothing to install, as for an app with no dependencies. If there's anything to install, the build fails with "Missing Bun lockfile".

devDependencies are installed for your build scripts, which run next, and removed once they finish.

Private packages and registries#

Use Bun's usual configuration. Declare the scope in bunfig.toml, with the token read from a secret so it never enters the repo:

bunfig.toml
[install.scopes]
"@my-org" = { token = "$MY_ORG_NPM_TOKEN", url = "https://npm.pkg.example.com/" }

Then add MY_ORG_NPM_TOKEN as a secret.

Bun also reads .npmrc, so a registry already configured there for npm keeps working. See Bun's scopes and registries reference for every option.

Warning

Never commit tokens. Add them as secrets.

Lockfiles#

App has Lockfile
Dependencies Required. Commit bun.lock (or bun.lockb).
No dependencies Not needed. Mark the repo as a Bun app with bunfig.toml, .bun-version, or a packageManager field instead.

Regenerate the lockfile with bun install whenever package.json changes, and commit it.

If package.json and the lockfile disagree, the install fails; bun install --frozen-lockfile shows the same error locally. Delete lockfiles from other package managers.

Bun as the asset builder for other languages#

A Ruby, PHP, or Rust app with a package.json for its frontend gets that frontend built with Bun when a bun.lock is committed beside the package.json.

App Detected by What Bun does web process
Ruby Gemfile.lock Installs Bun and your JavaScript dependencies, runs your build scripts. bun is on PATH when rake assets:precompile runs. Your Procfile, or the web process detected from your gems.
PHP composer.json Runs after composer install, so vendor/ is in place. Installs Bun and your JavaScript dependencies, runs your build scripts. Your Procfile. Without one, see below.
Rust Cargo.toml Runs before cargo build. Installs Bun and your JavaScript dependencies, runs your build scripts. Your Procfile. Without one, your Rust binary.

In all three:

  • The install, build scripts, and pruning are the same as for a Bun app, described above.
  • A web line in your Procfile always decides the web process.
  • With a Procfile that has no web line, a PHP or Rust app that has a root server.js, index.js, server.ts, or index.ts starts that file with Bun as web. Declare web in the Procfile.
  • Without a Procfile, a Rails, Rack, or Rust app still starts its own web process, whatever package.json says.
  • Without a Procfile, a PHP app, or a Ruby app with no detected web process, starts with Bun when the repo gives it a way to: a start script in package.json, or a root server.js, index.js, server.ts, or index.ts. Add a Procfile with a web line to keep your own server in charge.
  • In a PHP or Rust app, Bun is the only JavaScript runtime installed. A build tool that starts itself with node, such as Vite, runs on Bun. A Ruby app gets Node.js as well.
  • The Bun version is pinned the same way; see Runtime versions.

Each language documents this from its own side: Ruby on Primcloud → Detection, PHP → Customizing the build, and Rust on Primcloud → Frontend assets.