Primcloud
Docs menu

Runtime versions

Which Bun versions Primcloud installs, how to pin one with .bun-version, packageManager, or engines.bun, and how to upgrade.

On this page

Primcloud installs the Bun version your repo asks for. Three places can name it; if none does, you get Primcloud's default.

Supported versions#

Primcloud doesn't keep its own list of Bun releases. A pinned version is fetched from Bun's official releases at build time, so any Bun version that has a Linux release is installable.

The default moves forward over time. The build log names it whenever it's used: Bun version not specified, using <version>.

Pinning a version#

The first source that names a version wins:

Order Source Accepts
1 .bun-version at the repo root An exact version
2 packageManager in package.json bun@<exact version>
3 engines.bun in package.json An exact version, or a semver range

An exact version is major.minor.patch. A leading v or = is accepted (1.4.2, v1.4.2, =1.4.2).

.bun-version: a file holding nothing but the version:

.bun-version 
1.4.2

packageManager: the Corepack-style field. A +<hash> suffix is accepted and ignored. A packageManager naming another tool is skipped, and resolution moves on to engines.bun:

package.json 
{
  "packageManager": "[email protected]"
}

engines.bun: an exact version pins it, as above. Anything else is read as a semver range:

package.json 
{
  "engines": {
    "bun": "^1.4.0"
  }
}

Ranges resolve to the default, or not at all. A range isn't matched against every Bun release. If Primcloud's default version satisfies the range, the default is installed. If it doesn't, the build fails with an "Unsupported Bun version range" error asking for an exact version. A range is a way to say "the default is fine as long as it's at least this." To get a specific Bun, pin it exactly.

.bun-version and packageManager take exact versions only. A range, latest, or a trailing comment in either one fails the build with an "Invalid Bun version" error.

If nothing names a version, the default is installed. That's fine for a spike, but the default changes over time. Pin an exact version so a rebuild can't move you to a new Bun without warning.

Upgrading#

Change the pin, commit, and push:

.bun-version 
1.4.0

becomes:

.bun-version 
1.4.2

The next build downloads the new Bun. Run bun install locally with the new version first. If it rewrites your lockfile, commit the result. The build installs with --frozen-lockfile and fails on a lockfile that needs changes.

Read the Bun release notes before a bump.

When a version can't be resolved#

A pinned version that isn't a Bun release (a typo, or a version with no Linux build) fails the build with an "Unknown Bun version" error. Fix the pin to a version listed in Bun's releases.