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:
[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
webline in yourProcfilealways decides thewebprocess. - With a
Procfilethat has nowebline, a PHP or Rust app that has a rootserver.js,index.js,server.ts, orindex.tsstarts that file with Bun asweb. Declarewebin theProcfile. - Without a
Procfile, a Rails, Rack, or Rust app still starts its ownwebprocess, whateverpackage.jsonsays. - Without a
Procfile, a PHP app, or a Ruby app with no detectedwebprocess, starts with Bun when the repo gives it a way to: astartscript inpackage.json, or a rootserver.js,index.js,server.ts, orindex.ts. Add aProcfilewith awebline 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.