Status of package installation and registry support in browser-containers,
plus an exploration of which package managers and registries we can realistically
support in a browser-only runtime. The architectural decision is recorded in
ADR-0004.

Current state

npm works today via npm-in-browser: the real npm/cli source compiled to a
single ESM module with Node globals shimmed at build time. It uses fetch()
against registry.npmjs.org (CORS required), reads and writes
package-lock.json, and blocks install scripts. It is not a reimplementation
of npm, it is the real CLI.

This is the baseline. Everything below is evaluated relative to it.

Registries

npm registry

Fully supported via npm-in-browser. Tarballs resolve against
registry.npmjs.org and install into the virtual filesystem.

JSR (jsr.io)

Feasible, ~1 day of work, high ROI.

JSR is the Deno team registry for native TypeScript packages. It exposes an
npm-compatibility layer at npm.jsr.io: every package is mirrored there as
@jsr/scope__name (double underscore) under the standard npm registry
protocol (corgi install manifests, tarballs). The mapping from a
jsr:@scope/name specifier to @jsr/scope__name is a pure syntactic
transform. There is no JSR-specific install API beyond this.

Bringing tier-1 JSR support requires:

1. Write @jsr:registry=https://npm.jsr.io to .npmrc so npm-in-browser
   resolves @jsr/* scopes against the JSR mirror.
2. Fix parsePackageSpecifier (packages/npm/src/package-manager.ts) so a
   jsr: specifier emits @jsr/scope__name instead of @scope/name.
3. Add a bundler jsr:-alias plugin (mirrors the existing node-alias plugin
   in packages/wasm-registry/src/bundle.ts) so import "jsr:@foo/bar"
   rewrites to the installed @jsr/foo__bar package.

Publishing to JSR is out of scope for a browser runtime.

Package manager CLIs

The central question: can we run the real CLI for other package managers
(yarn, pnpm, bun), the way npm-in-browser runs the real npm CLI?

yarn v1

Feasible via lockfile translation (~1 day). Running the real yarn CLI
needs a virtual symlink table so its node_modules walker resolves layouts.
Translation of yarn.lock into an installed graph is cheaper and avoids
ongoing maintenance.

pnpm

Impossible without a re-architecture. Two structural blockers:

1. The content-addressable store hardlinks packages via fs.linkSync. The
   browser Filesystem Access API and OPFS have no hardlink concept.
2. The virtual store is 100% symlinks (symlinkDir). The node-linker=hoisted
   option changes strategy within the isolated layout, it does not eliminate
   symlinks.

pnpm lockfile translation (~1 day) gives the same installed graph without the
CLI.

bun

Infeasible. The blocker is not the language. Bun migrated its installer
from Zig to Rust in v1.4.0, but the underlying bun_sys calls libc syscalls
with no WASI equivalent: clonefile/hardlink/symlinkat,
connect/recv (TCP, where WASIp1 sockets are UDP-only), and futex. There
is no JS API for install (only a parseLockfile test helper). It cannot run
under our WASI shim, which provides filesystem, args, and env only.

Browser-native package manager candidates

We evaluated every candidate that claims browser or cross-runtime viability.
None is adoptable today. The table records why.

The single largest blocker across all candidates is server-only HTTP:
every Rust-based candidate uses reqwest or undici, neither of which runs in
a browser without a full rewrite to fetch.

Supporting libraries

These are not package managers, but libraries that could feed into our install
or resolution layer.

vlt engine (@vltpkg/*)

Strongest candidate for resolver and install-logic reuse. The vltpkg graph
engine is separately importable, and browser variants exist:
@vltpkg/spec/browser, @vltpkg/graph/browser, @vltpkg/dep-id/browser,
@vltpkg/security-archive/browser. The public API (actual.load(),
ideal.build(), reify(), install()) takes a scurry filesystem
abstraction, a packageInfo manifest fetcher, and a packageJson reader.

Graph computation (actual, ideal, diff) is link-format-agnostic. The only
filesystem coupling is in reify, which writes the node_modules layout. The
@vltpkg/cache hardlink CAS and the @vltpkg/registry-client undici wrapper
are the blockers, but both are skippable if we supply our own scurry adapter
backed by VfsBus and our own fetch-based registry client.

The scurry interface is not documented in the public docs. Read the source
for the type contract before committing to this path.

@jspm/generator

Possible replacement for the esm.sh resolver plugin. A browser-runnable
import-map generator that traces dependency graphs, resolves exports and
imports with environment conditionals (browser, module, development,
production), and outputs WICG import-map JSON. It supports a customResolver
per specifier and an inputMap that acts as a lockfile.

It does not support JSR specifiers. If we adopt it, JSR handling stays
separate. A conservative adoption path keeps esm.sh as the CDN provider behind
a custom resolver. Apache-2.0, active.

@yarnpkg/fslib

Useful as an adapter pattern, not as a symlink emulator. Pure TypeScript,
BSD-2-Clause, no native dependencies, 100% browser-viable. Its FakeFS
abstract class, ProxiedFS adapter (implement mapToBase/mapFromBase and
inherit delegation), and patchFs runtime patcher are clean primitives.

However, VirtualFS does not emulate symlinks. It is a path-mapping layer
for the Yarn PnP $$virtual scheme. symlinkSync/readlinkSync/lstatSync
all proxy through to the base filesystem unchanged. There is no hardlink
emulation anywhere in fslib. Vendoring it does not solve the symlink problem;
the 20-line fix of forwarding memfs Volume internals through the fs API solves
80% of what fslib would.

pkg.pr.new

Secondary, CI-only tarball source. A StackBlitz Labs platform that runs a
GitHub Action to npm pack a package at a given commit, PR, or branch, then
serves the .tgz from Cloudflare R2 at pkg.pr.new/{owner}/{repo}/{pkg}@{ref}.
It is not a CDN: it serves tarballs, no transpilation, no ESM rewriting.
esm.sh already consumes it via a /pr/ endpoint.

Integration value is as an additional URL-tarball dependency source for
previewing PR builds. It requires a GitHub App and workflow on the source repo,
so end users cannot publish locally. MIT, adopted by Vite, Vue, Svelte, Nuxt,
Biome. No published SLA or rate limits.

The symlink and hardlink blocker

Everything above converges on one root cause: the browser filesystem (memfs
plus OPFS) has no symlink or hardlink semantics. This gates:

• the real pnpm CLI (hardlinks plus symlink virtual store),
• the real yarn v1 CLI (needs to walk symlinked node_modules),
• vltpkg reify() (writes node_modules layout with symlinks),
• @yarnpkg/fslib (proxies symlink ops to the base filesystem).

The fix is small and local: forward memfs Volume’s internal symlinkSync,
readlinkSync, and lstatSync to the public fs API (roughly 20 lines).
memfs already implements these internally, they are just not exposed. Once that
exists, yarn v1 lockfile translation, vlt engine reify, and fslib patchFs
integration all become viable.

Hardlinks (needed by pnpm’s CAS and vltpkg’s @vltpkg/cache) require a
separate in-memory inode table. There is no shortcut here. This is why pnpm
remains lockfile-translation-only even after the symlink work lands.

WinterTC positioning

WinterCG, now formalized as Ecma TC55 and ECMA-429, defines the
minimum common Web API surface that every non-browser JavaScript runtime agrees
to provide. We are already roughly 90% compliant through native Web APIs plus
node-web-shims.

Marketing a measurable WinterTC compliance percentage is worthwhile as a tier
label between Web-Standard and full Node. Deno markets “WinterCG-compliant”
and Bun markets “web-interoperable”. The official test suite (a WPT subset) is
not yet published, so any claim should be hedged as “ECMA-429 2025
snapshot-aligned” until a runnable suite exists. See
compat.md.

Decision

See ADR-0004 for the formal record.
In short: keep npm-in-browser, add JSR via npm.jsr.io, add lockfile
translation for yarn and pnpm, build the symlink table on memfs, and defer a
browser-native package manager until install performance becomes a real pain
point.

Roadmap (priority order)

Worked items here are exploration conclusions, not committed tasks. The
implementation roadmap will be tracked in the GitHub Project.

1. JSR tier-1 (~1 day): fix parsePackageSpecifier, add .npmrc entry,
   add bundler jsr:-alias plugin.
2. Lockfile translation (~1 day each for yarn and pnpm): no new deps,
   high adoption value.
3. Symlink table on memfs (~2 to 3 days): forward memfs internals through
   the fs API. Unlocks yarn v1, vltpkg reify, fslib patchFs.
4. WinterTC compliance audit (~1 day): close navigator.userAgent and
   rejection-event gaps, publish a percentage against ECMA-429.
5. Browser-native package manager (deferred, ~2 to 3 weeks): only if
   install performance becomes a user pain point. Reference rnpm’s extraction
   model (copy and rename, no symlinks or hardlinks) and aube’s lockfile
   handling. Build on fetch and VFS primitives.

Explicitly skipped: real npm CLI port (~2 to 3 weeks plus perpetual per-version
maintenance), real pnpm CLI (impossible), bun install (infeasible), wholesale
adoption of aube or pacquet.