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, or the newest available one if it doesn't ask.

Available versions#

The Bun versions Primcloud installs are part of the Primcloud Runtime: Bun 1.4.0 and newer, with new releases added over time. The build log names the version each build installed.

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: a +<hash> suffix is accepted and ignored. A packageManager naming another tool is skipped:

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"
  }
}

A range installs the newest available version it allows. If none does, the build fails with "Unsupported Bun version range". 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 newest available version is installed, and it changes as new releases are added. Pin an exact version so a rebuild can't move you to a new Bun unexpectedly.

Upgrading#

Change the pin, commit, and push:

.bun-version
1.4.0

becomes:

.bun-version
1.4.2

Run bun install locally with the new version first, and commit the lockfile if it changes; the build 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 outside the available versions, often a typo, fails the build with an "Unsupported Bun version" error. The error names the oldest and newest available versions; pin one in that span.