Skip to content

fix(docs): pull bb.js runtime deps via portal in examples#24510

Open
charlielye wants to merge 2 commits into
nextfrom
cl/docs-examples-portal-deps
Open

fix(docs): pull bb.js runtime deps via portal in examples#24510
charlielye wants to merge 2 commits into
nextfrom
cl/docs-examples-portal-deps

Conversation

@charlielye

Copy link
Copy Markdown
Contributor

Problem

ci/docs/examples/bootstrap.sh execute is failing repo-wide (every fresh install since 2026-06-26) with:

@aztec/bb.js/src/barretenberg_wasm/fetch_code/node/index.ts:4
import pako from 'pako';
SyntaxError: The requested module 'pako' does not provide an export named 'default'

Root cause

The recursive_verification example links @aztec/bb.js via yarn's link: protocol, which symlinks the package but does not install its own dependencies. To compensate, the example's config.yaml hand-listed bb.js's runtime deps (pako, msgpackr, comlink, idb-keyval, commander, tslib) — but unversioned (npm:pako). The bootstrap turns those into yarn add pako = latest.

pako@3.0.0 (published 2026-06-26) dropped the CommonJS/ESM default export (its ESM entry moved to named-exports-only), so bb.js's import pako from 'pako' throws under the runner's tsx/esm + --preserve-symlinks. Pre-06-26 the same bare install resolved 2.2.0 and worked; that's why older next runs were green.

Fix

Add portal: support to the examples dependency parser (lib.sh/bootstrap.sh) and pull bb.js via portal: instead of link: + a hand-mirrored dep list. portal: installs the package's declared dependencies at the versions it pins, so:

  • pako resolves to 2.2.0 (bb.js pins ^2.1.0), not 3.0.0.
  • The manual npm: list is deleted — bb.js's own package.json is the single source of truth, so this drift/float class of regression can't recur.

link: (which intentionally does not install deps) remains for the noir packages.

Verification

  • Reproduced locally on the CI Node (v24.12.0): import pako from 'pako' works on 2.1.0/2.2.0, throws the exact CI error on 3.0.0.
  • Verified yarn add @aztec/bb.js@portal:<path> installs bb.js's transitive deps at its pinned ranges (pako 2.2.0, msgpackr 1.12.1, comlink 4.4.2); yarn itself notes portal + --preserve-symlinks is the intended pairing (which the runner already uses).
  • Verified the parser emits @aztec/bb.js@portal:<repo>/barretenberg/ts/bb.js with no manual npm deps and no warnings; bash -n clean.
  • Not run locally: the full docs/examples execute pipeline (needs the built monorepo + a live network) — relying on CI for the end-to-end confirmation.

…ng them

The recursive_verification example links @aztec/bb.js via link:, which does not
install the linked package's own dependencies, so the config hand-listed bb.js's
runtime deps (pako, msgpackr, comlink, idb-keyval, commander, tslib). They were
unversioned, so the bootstrap ran 'yarn add pako' = latest; when pako 3.0.0
(2026-06-26) dropped the ESM default export bb.js's 'import pako from pako'
relies on, ci/docs/examples/bootstrap.sh execute broke on every fresh install.

Add portal: support to the examples dependency parser and pull bb.js via portal:,
which installs its dependencies at the versions bb.js pins (pako resolves to
2.2.0, not 3.0.0). Delete the hand-mirrored npm list: bb.js's own package.json is
now the single source of truth, so this class of drift/float regression can't
recur. link: (no dep install) remains for the noir packages.
@charlielye charlielye requested a review from a team as a code owner July 3, 2026 17:49
…example

Switching bb.js to portal: fixed bb.js's own pako import but surfaced a second
pako consumer: @aztec/noir-noir_js (used in its debug.mjs) also declares
pako ^2.1.0. It is link:'d (not portal:'d) because its @aztec/noir-* siblings
are pinned to unpublished 1.0.0-beta.21 versions that portal cannot fetch, and
link: does not install a package's own deps — so noir_js's pako must be supplied
explicitly. Pinned to noir_js's own range (^2.1.0) so it can't float to the
breaking pako 3.0.0 (dropped ESM default export).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant