Replace Yarn with Bun before hosted deployment #20

Closed
opened 2026-11-07 21:51:00 +00:00 by martin · 7 comments
Owner

Goal

Make Bun the workspace package manager and script entry point before hosted deployment, while preserving working Backstage development, validation, and packaging.

Scope

Replacing Yarn does not automatically mean replacing Node as the Backstage runtime or Jest with Bun's test runner. Evaluate and document those choices separately; retain supported Node where needed. Do not combine this migration with unrelated dependency majors.

Acceptance criteria

  • Pin a Bun version and validate Backstage CLI/workspace compatibility with a clean installation.
  • Migrate to a committed Bun lockfile, preserving dependency overrides/resolutions and reviewing dependency graph changes.
  • Validate native dependencies and lifecycle scripts, especially better-sqlite3 and node-gyp; explicitly allow only required install scripts.
  • Replace Yarn workspace/script commands while preserving catalog sync before development startup.
  • Update repository CI to use frozen-lockfile Bun installation and verify typecheck, lint, formatting, existing tests, E2E checks, and frontend/backend builds.
  • Update Docker production dependency installation/packaging to eliminate yarn workspaces focus and prove image startup with the chosen runtime and matching native-module ABI.
  • Update the declared development toolchain, README, package-manager metadata, repository instructions, and Renovate configuration.
  • Remove obsolete Yarn configuration and lockfile only after equivalent workflows pass; document compatibility limitations and the runtime decision.

Sequencing

Complete the dependency/test baseline first. This issue is a mandatory dependency of hosted deployment.

Phase

1 — Trustworthy foundation

Completed in PR #42, merged as 4fb240bf. The merged application-checks pipeline #130 passed every step on Node 22 with Bun 1.4.4, including E2E. A production-install/startup simulation using the Dockerfile skeleton and bundle passed on Node 22: better-sqlite3 ABI 127 loaded and the backend served the frontend with HTTP 200. Renovate's Bun manager detects bun.lock by default, so no repository-specific Renovate rule was needed; the existing shared presets remain in place. Follow-ups are tracked separately in #30 (actual image build/deployment validation) and #47 (move off temporary Node 22 before EOL).

## Goal Make Bun the workspace package manager and script entry point before hosted deployment, while preserving working Backstage development, validation, and packaging. ## Scope Replacing Yarn does not automatically mean replacing Node as the Backstage runtime or Jest with Bun's test runner. Evaluate and document those choices separately; retain supported Node where needed. Do not combine this migration with unrelated dependency majors. ## Acceptance criteria - [x] Pin a Bun version and validate Backstage CLI/workspace compatibility with a clean installation. - [x] Migrate to a committed Bun lockfile, preserving dependency overrides/resolutions and reviewing dependency graph changes. - [x] Validate native dependencies and lifecycle scripts, especially `better-sqlite3` and `node-gyp`; explicitly allow only required install scripts. - [x] Replace Yarn workspace/script commands while preserving catalog sync before development startup. - [x] Update repository CI to use frozen-lockfile Bun installation and verify typecheck, lint, formatting, existing tests, E2E checks, and frontend/backend builds. - [x] Update Docker production dependency installation/packaging to eliminate `yarn workspaces focus` and prove image startup with the chosen runtime and matching native-module ABI. - [x] Update the declared development toolchain, README, package-manager metadata, repository instructions, and Renovate configuration. - [x] Remove obsolete Yarn configuration and lockfile only after equivalent workflows pass; document compatibility limitations and the runtime decision. ## Sequencing Complete the dependency/test baseline first. This issue is a mandatory dependency of hosted deployment. ## Phase 1 — Trustworthy foundation _Completed in PR #42, merged as 4fb240bf. The merged application-checks pipeline #130 passed every step on Node 22 with Bun 1.4.4, including E2E. A production-install/startup simulation using the Dockerfile skeleton and bundle passed on Node 22: better-sqlite3 ABI 127 loaded and the backend served the frontend with HTTP 200. Renovate's Bun manager detects bun.lock by default, so no repository-specific Renovate rule was needed; the existing shared presets remain in place. Follow-ups are tracked separately in #30 (actual image build/deployment validation) and #47 (move off temporary Node 22 before EOL)._
Author
Owner

Existing implementation references from the context vault

Consult the vault and referenced repositories before making toolchain/packaging decisions:

Additional migration gate: verify current marker-file routing and effective Woodpecker configuration before adding/merging bun.lock. The documented injected validation is Astro/Biome-oriented and publication/promotion workflows have persistent effects; they are not automatically suitable for Backstage. Confirm that migration does not inadvertently activate incompatible validation or premature deployment. Any necessary shared-CI changes require separately agreed infrastructure work.

Vault notes are architectural context, not proof of current workflow applicability; verify against actual configuration and observed pipeline runs.

## Existing implementation references from the context vault Consult the vault and referenced repositories before making toolchain/packaging decisions: - [`projects/toolbox/learnings.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/toolbox/learnings.md): Bun dependencies via bun2nix, Nix-built OCI images, and a production-startup test of the compiled artifact. Reuse the verification boundary, not Astro-specific runtime assumptions. - [`projects/backstage/architecture.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/backstage/architecture.md): baseline discovery rationale and the original missing Yarn got-patch workaround; review the override during migration instead of deleting it blindly. - [`projects/nixos/woodpecker-global-workflow-architecture.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/nixos/woodpecker-global-workflow-architecture.md): the documented `bun-astro` rule matches `bun.lock` plus `package.json`, injecting verify/push/deploy workflows. **Additional migration gate:** verify current marker-file routing and effective Woodpecker configuration before adding/merging `bun.lock`. The documented injected validation is Astro/Biome-oriented and publication/promotion workflows have persistent effects; they are not automatically suitable for Backstage. Confirm that migration does not inadvertently activate incompatible validation or premature deployment. Any necessary shared-CI changes require separately agreed infrastructure work. Vault notes are architectural context, not proof of current workflow applicability; verify against actual configuration and observed pipeline runs.
Author
Owner

Progress on the Bun migration is in draft PR #42 (branch build/bun-package-manager, head 74081a9).

What is validated:

  • Bun 1.4.4 migrates the Yarn 4.18 lockfile with zero version drift; bun.lock is committed and the Yarn files are removed.
  • Clean bun install --frozen-lockfile (2651 packages), tsc, lint:all, prettier:check, Jest, frontend/backend builds, and Playwright E2E (5 passed) all pass.
  • Production simulation on Node 24: bun install --omit=dev, backend starts, serves the built frontend, and the ABI 137 better-sqlite3 binary loads.
  • Python-free CI install on Node 24 with python3 and gcc removed from PATH: install, unit tests, and both builds pass because better-sqlite3 uses its prebuilt binary. The CI apt step now installs only ca-certificates, curl, and unzip.

Still open before merge:

  • The global Woodpecker bun-astro rule matches bun.lock + package.json and would inject Astro-specific verify/push/deploy workflows. That shared-config exclusion needs separate approval (tracked in the PR body).
  • The Docker image was simulated, not built, because the local daemon is inaccessible.
  • The new CI workflow has not run yet; its first pipeline comes with the push to the default branch.
Progress on the Bun migration is in draft PR #42 (branch `build/bun-package-manager`, head `74081a9`). What is validated: - Bun 1.4.4 migrates the Yarn 4.18 lockfile with zero version drift; `bun.lock` is committed and the Yarn files are removed. - Clean `bun install --frozen-lockfile` (2651 packages), `tsc`, `lint:all`, `prettier:check`, Jest, frontend/backend builds, and Playwright E2E (5 passed) all pass. - Production simulation on Node 24: `bun install --omit=dev`, backend starts, serves the built frontend, and the ABI 137 `better-sqlite3` binary loads. - Python-free CI install on Node 24 with `python3` and `gcc` removed from `PATH`: install, unit tests, and both builds pass because `better-sqlite3` uses its prebuilt binary. The CI apt step now installs only `ca-certificates`, `curl`, and `unzip`. Still open before merge: - The global Woodpecker `bun-astro` rule matches `bun.lock` + `package.json` and would inject Astro-specific verify/push/deploy workflows. That shared-config exclusion needs separate approval (tracked in the PR body). - The Docker image was simulated, not built, because the local daemon is inaccessible. - The new CI workflow has not run yet; its first pipeline comes with the push to the default branch.
Author
Owner

The shared-workflow blocker now waits on a direct per-workflow opt-out: Personal/woodpecker-extension#50 adds ignored_workflows to woodpecker.toml.

#44 adds the file here and depends on Personal/nixos-configuration#68, which bumps and deploys the extension after #50 ships. The label-based match_not_labels approach is dropped.

The shared-workflow blocker now waits on a direct per-workflow opt-out: Personal/woodpecker-extension#50 adds `ignored_workflows` to `woodpecker.toml`. #44 adds the file here and depends on Personal/nixos-configuration#68, which bumps and deploys the extension after #50 ships. The label-based `match_not_labels` approach is dropped.
Author
Owner

Validation update: PR #42's pull-request pipeline is green at f1d6d1f — all repository-owned checks pass, including E2E.

The last failure was Playwright's browser channel: @backstage/e2e-test-utils defaults generated projects to chrome, while CI installs Chromium. playwright.config.ts now uses channel: 'chromium'; the Nix shell still supplies PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH locally.

Remaining blocker is unchanged: the branch's push pipeline runs the global bun-verify workflow from the shared bun-astro rule and fails there. #44 (via Personal/nixos-configuration#68 and Personal/woodpecker-extension#50) is the planned opt-out.

Validation update: PR #42's pull-request pipeline is green at `f1d6d1f` — all repository-owned checks pass, including E2E. The last failure was Playwright's browser channel: `@backstage/e2e-test-utils` defaults generated projects to `chrome`, while CI installs Chromium. `playwright.config.ts` now uses `channel: 'chromium'`; the Nix shell still supplies `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` locally. Remaining blocker is unchanged: the branch's push pipeline runs the global `bun-verify` workflow from the shared `bun-astro` rule and fails there. #44 (via Personal/nixos-configuration#68 and Personal/woodpecker-extension#50) is the planned opt-out.
Author
Owner

The blocker now has a simpler fix. Rather than a repository-local opt-out, the shared bun-astro rule will require an Astro config file (astro.config.*) in addition to bun.lock and package.json; see Personal/nixos-configuration#68.

This removes the false positive for Backstage without an extension release or woodpecker.toml. #44 is closed as superseded, and Personal/woodpecker-extension#50 no longer blocks #42. PR #42 can merge once #68 is deployed.

The blocker now has a simpler fix. Rather than a repository-local opt-out, the shared `bun-astro` rule will require an Astro config file (`astro.config.*`) in addition to `bun.lock` and `package.json`; see Personal/nixos-configuration#68. This removes the false positive for Backstage without an extension release or `woodpecker.toml`. #44 is closed as superseded, and Personal/woodpecker-extension#50 no longer blocks #42. PR #42 can merge once #68 is deployed.
Author
Owner

PR #42 is merged into main (4fb240bf).

Done:

  • Bun 1.4.4 replaces Yarn; bun.lock migrated with no version drift; patches/@backstage%2Fcli-module-build@0.1.9.patch keeps Backstage's packager on Bun.
  • Woodpecker application-checks passes on Node 22 (pipeline #128), including E2E.
  • The global bun-astro rule requires an Astro config (Personal/nixos-configuration#68), so Backstage no longer receives bun-verify, bun-push, or bun-deploy.

Follow-ups:

  • Personal/backstage#47: move CI and the image off Node 22 before its April 2027 end-of-life.
  • Personal/backstage#30: build and start the Docker image (not yet built locally; the Docker daemon is inaccessible from this environment).
  • backstage-cli versions:bump remains Yarn-lockfile-only; use bun update (documented in the README).
PR #42 is merged into `main` (`4fb240bf`). Done: - Bun 1.4.4 replaces Yarn; `bun.lock` migrated with no version drift; `patches/@backstage%2Fcli-module-build@0.1.9.patch` keeps Backstage's packager on Bun. - Woodpecker `application-checks` passes on Node 22 (pipeline #128), including E2E. - The global `bun-astro` rule requires an Astro config (Personal/nixos-configuration#68), so Backstage no longer receives `bun-verify`, `bun-push`, or `bun-deploy`. Follow-ups: - Personal/backstage#47: move CI and the image off Node 22 before its April 2027 end-of-life. - Personal/backstage#30: build and start the Docker image (not yet built locally; the Docker daemon is inaccessible from this environment). - `backstage-cli versions:bump` remains Yarn-lockfile-only; use `bun update` (documented in the README).
Author
Owner

Progress

Completed by PR #42, merged as 4fb240bf.

  • Post-merge Woodpecker pipeline #130 passed all application-checks, including E2E, with Node 22 and Bun 1.4.4.
  • Re-ran the production dependency-install/startup simulation using the Dockerfile skeleton and bundle on Node 22: better-sqlite3 ABI 127 loaded, the backend started, and the packaged frontend returned HTTP 200.
  • Renovate's built-in Bun manager recognizes bun.lock; the existing shared presets don't disable it, so no repository-specific Renovate change was needed.
  • Node 22's eventual upgrade is tracked in #47. Building/deploying the actual container image remains part of #30.

All acceptance criteria for the Bun package-manager migration are satisfied; closing #20.

## Progress Completed by PR #42, merged as `4fb240bf`. - Post-merge Woodpecker pipeline #130 passed all `application-checks`, including E2E, with Node 22 and Bun 1.4.4. - Re-ran the production dependency-install/startup simulation using the Dockerfile skeleton and bundle on Node 22: `better-sqlite3` ABI 127 loaded, the backend started, and the packaged frontend returned HTTP 200. - Renovate's built-in Bun manager recognizes `bun.lock`; the existing shared presets don't disable it, so no repository-specific Renovate change was needed. - Node 22's eventual upgrade is tracked in #47. Building/deploying the actual container image remains part of #30. All acceptance criteria for the Bun package-manager migration are satisfied; closing #20.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/backstage#20
No description provided.