research: can Bun zero-install respect package.json versions (not fetch latest)?

[vivek7405]

Question

Can a zero-install Bun app (bun create webjs --no-install, then bun run dev / start via the webjs-bun.mjs bootstrap with no node_modules) RESPECT the package.json versions (and ideally bun.lock) instead of fetching latest?

Seed finding (verified this session, fresh cache)

Bun's bun --bun <file> auto-install (the exact zero-install run path) IGNORES both package.json versions AND a committed bun.lock, fetching latest for any bare import not physically in node_modules:

• A package.json pinning zod EXACTLY to 3.22.4 ran zod 4.4.3.
• Keeping a bun.lock that pinned 3.22.4 (with node_modules deleted) STILL ran 4.4.3.
• Only bun install (which materializes node_modules) honors the manifest/lockfile.

So the #675 zero-install path runs UNPINNED LATEST deps, a breaking-major hazard. This is why #682 (defaulting bun create to --no-install) was closed, and why #683 corrects the docs to say so plainly. If this research finds a version-respecting mechanism, #682's default-flip becomes viable.

Avenues to investigate (for the agent who picks this up)

1. A bunfig.toml [install] setting, or any Bun flag / env var, that makes auto-install honor the manifest/lockfile rather than fetching latest.
2. Bun.plugin onResolve: webjs already registers a Bun.plugin for TS-strip + action seeding (packages/server/src/action-seed-bun.js). An onResolve hook could intercept bare specifiers and resolve them to the package.json/bun.lock-pinned version (read the manifest + lockfile at boot, rewrite resolution to the pinned tarball in the cache).
3. A lightweight pre-resolve step: on first run, read package.json + bun.lock and warm Bun's global cache at the EXACT versions (without a full node_modules materialize), so the subsequent auto-install resolves the pinned copies from cache.
4. Whether a private registry mirror + a warmed/pinned cache (the sandbox+PaaS direction) is the only robust fix at scale.
5. Confirm whether bun run <script> differs from bun --bun <file> here, and whether a newer Bun version changes the behavior (re-test on the latest Bun).

Cross-references

• Zero-install dev/start on Bun via native auto-install (carve from #669) #675 (the zero-install bootstrap this concerns).
• Zero-install dev: no install command, transparent resolution (Node+Bun) #669 (the zero-install initiative; the Node half faces the same pin-respecting question for its module.register resolve-hook).
• docs: correct #675 zero-install caveat (Bun runs latest, ignores package.json + bun.lock) #683 (the doc correction stating zero-install runs latest).
• bun create defaults to no install (zero-install onboarding); node unchanged #682 (closed; the default-flip this research would unblock).

This is a forward-looking research task. Findings go into this same issue (comments + a curated conclusion in the body), then close it when the research concludes.

[vivek7405]

Findings so far (investigation in progress)

1. Confirmed: the default run-path auto-install fetches latest, ignoring pins. Twice, fresh cache: a package.json pinning zod EXACTLY to 3.22.4, run via bun --bun <file> (the path bun run dev / start take), resolved zod 4.4.3 (latest). A committed bun.lock pinning 3.22.4 (node_modules deleted) does not change it. So the operative behavior for the zero-install run path is "fetch latest", not "honor the manifest/lockfile".

2. Bun's --install modes are a timing lever, not a version lever. bun --help documents --install=auto (default, auto-install when no node_modules), --install=fallback / -i (missing packages only), --install=force (always), and --no-install. These control WHEN auto-install runs, not WHICH version it resolves; none is documented to read the manifest/lockfile version for the run path. (The explicit-flag forms ENOENT'd in a quick test under a transient resolve blip, so a clean per-mode version check is still worth re-running on stable network, but the semantics suggest they will not pin.)

3. Only bun install honors the manifest/lockfile, because it materializes node_modules; the run-path auto-install resolves bare specifiers straight to latest.

Avenue assessment

• bunfig.toml / flags: unpromising. The install modes are timing-only; no documented setting makes the run-path auto-install honor the pinned version.
• Bun.plugin onResolve (most promising, the next concrete step): webjs already registers a Bun.plugin (TS-strip + action seeding, packages/server/src/action-seed-bun.js). A spike: add an onResolve that, for a bare specifier, reads the app's package.json + bun.lock at boot and rewrites resolution to the pinned version (its tarball already in Bun's cache, or trigger a pinned fetch). Open questions for the spike: can onResolve return a cached pinned path without a full node_modules; does it compose with the existing TS-strip plugin; does it cover transitive deps or only top-level.
• Private registry mirror + warmed pinned cache (robust at scale): the sandbox+PaaS direction. A controlled mirror plus a cache warmed at the lockfile versions sidesteps the run-path-fetches-latest problem entirely. Heavier, but the durable answer for a platform.

Next step

Spike avenue (2): a Bun.plugin onResolve that pins bare specifiers from package.json/bun.lock, tested on stable network. If it works, link a draft spike PR here and a webjs-file-issue implementation task (which would also unblock the closed #682 default-flip). Re-run the per-mode version check on stable network to close out avenue (1).

[vivek7405]

Manual spike protocol (run on a stable machine, please report results)

Goal: determine whether a Bun.plugin onResolve hook can make zero-install Bun RESPECT the package.json/bun.lock version instead of fetching latest. Run all three; paste the output here. First note your Bun version: bun --version.

Setup (once)

mkdir /tmp/bun-pin && cd /tmp/bun-pin
printf '{ "name":"t", "type":"module", "dependencies": { "zod":"3.22.4" } }\n' > package.json

A. Baseline (confirm the problem)

rm -rf node_modules bun.lock ~/.bun/install/cache
printf "const v = await import('zod/package.json',{with:{type:'json'}}); console.log('A_VERSION=' + v.default.version);\n" > a.ts
bun --bun a.ts

REPORT: the A_VERSION= value. Expected bug: a 4.x (latest), NOT 3.22.4.

B. Does onResolve intercept a bare specifier at runtime?

printf "export const z = { tag: 'LOCAL_STUB' };\n" > stub.js
cat > preload.js <<'EOF'
import { plugin } from 'bun';
import { resolve } from 'node:path';
plugin({ name: 'x', setup(b) {
  b.onResolve({ filter: /^zod$/ }, () => {
    console.error('HOOK_FIRED');
    return { path: resolve(import.meta.dir, 'stub.js') };
  });
}});
EOF
printf "import { z } from 'zod'; console.log('B_TAG=' + z.tag);\n" > b.ts
rm -rf node_modules
bun --bun --preload ./preload.js b.ts

REPORT: did HOOK_FIRED print, and did B_TAG=LOCAL_STUB print? (If yes, runtime onResolve interception of a bare specifier works, the foundation of the approach.)

C. Can the plugin force the package.json-pinned version?

cat > preload-pin.js <<'EOF'
import { plugin } from 'bun';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
const pkg = JSON.parse(readFileSync(resolve(import.meta.dir, 'package.json'), 'utf8'));
const deps = { ...pkg.dependencies, ...pkg.devDependencies };
plugin({ name: 'pin', setup(b) {
  b.onResolve({ filter: /^[^.#/][^/]*$/ }, (args) => {
    const want = deps[args.path];
    if (!want) return;                       // not a declared dep, let Bun handle it
    // Materialize the EXACT pinned version into a local dir, then resolve to it.
    Bun.spawnSync(['bun', 'add', `${args.path}@${want}`, '--no-save'], { cwd: import.meta.dir, stdout: 'inherit', stderr: 'inherit' });
    return { path: resolve(import.meta.dir, 'node_modules', args.path, 'index.js') };
  });
}});
EOF
printf "const v = await import('zod/package.json',{with:{type:'json'}}); console.log('C_VERSION=' + v.default.version);\n" > c.ts
rm -rf node_modules
bun --bun --preload ./preload-pin.js c.ts

REPORT: the C_VERSION= value. If it is 3.22.4, the plugin successfully pinned (the spike works). If still 4.x or it errors, note the error.

Also worth reporting: does C still work with node_modules deleted but a committed bun.lock present (read the version from bun.lock instead of package.json)? And does C handle a TRANSITIVE dep (a dep-of-a-dep), or only top-level?

What the results tell us

• B works + C pins => the spike is viable; next is a real webjs-file-issue to build a pin-resolving plugin into the bootstrap (and it would unblock the closed bun create defaults to no install (zero-install onboarding); node unchanged #682 default-flip).
• B works + C does not pin => onResolve fires but cannot force the version this way; fall back to the private-registry-mirror + warmed-cache approach (the PaaS direction).
• B does not fire => runtime onResolve cannot intercept bare auto-install specifiers; the mirror/warmed-cache approach is the path.

[vivek7405]

Conclusion (research complete): NO in-process way to pin; a private registry mirror is the path

Ran the spike in a clean Bun 1.3.11 sprite (stable env). Verdict: a zero-install Bun app CANNOT be made to respect package.json/bun.lock versions in-process. The pin requires either bun install (materialized node_modules) or controlling the registry.

Evidence

• A (baseline): package.json pinning zod 3.22.4, fresh cache, bun --bun a.ts resolved zod 4.4.3 (latest). Auto-install ignores the pin. Reproduced.
• B2 (the decisive one): a --preload plugin loaded (PRELOAD_TOPLEVEL_RAN) and its setup() ran (PLUGIN_SETUP_RAN), but onResolve for zod NEVER fired (ONRESOLVE_FIRED absent) while the bare import still resolved. So Bun.plugin onResolve is bypassed for bare-specifier auto-install resolution. Avenue 2 (an onResolve hook that rewrites to the pinned version) does not work.
• C: the pin plugin (read package.json, bun add <pkg>@<pinned> in onResolve) never fired either; still 4.4.3. Consistent with B2.
• Warmed cache + --no-install: after bun add zod@3.22.4 populated the cache (confirmed zod@3.22.4 in bun pm cache), then dropping node_modules and running bun --bun --no-install gave Cannot find module 'zod/package.json'. So runtime resolution reads node_modules, not the global cache; warming the cache alone does not satisfy a zero-install run.
• --install modes (auto / fallback / force) are a TIMING lever (when to auto-install), not a version lever; none reads the manifest/lockfile version for the run path.

Why

Bun's auto-install is "fetch latest from the registry into node_modules on demand"; it consults neither package.json, nor bun.lock, nor a pre-warmed cache, nor onResolve plugins. Only bun install honors the manifest/lockfile, because it is what materializes node_modules, and runtime resolution reads node_modules.

So, the options to pin

1. bun install (materialize node_modules) before running. This is correct and pinned, but it is no longer "zero-install".
2. A private registry mirror whose available versions / latest tag are controlled, so auto-install's "fetch latest" resolves to the version you intend. This is the only way to keep the install-free run AND get pinned versions, and it is exactly the sandbox+PaaS direction (a controlled mirror + the run-path auto-install pointed at it). An in-app fix is not possible.

Impact

• bun create defaults to no install (zero-install onboarding); node unchanged #682 (default bun create to --no-install) stays closed: there is no in-process pinning fix, so defaulting to no-install means unpinned latest.
• docs: correct #675 zero-install caveat (Bun runs latest, ignores package.json + bun.lock) #683 (doc correction) is correct and now definitively grounded: zero-install runs latest, ignoring package.json + bun.lock.
• Zero-install dev: no install command, transparent resolution (Node+Bun) #669 (the Node half) faces the same reality: pinning needs node_modules or a controlled registry, not a resolve-hook over the live registry.
• The PaaS pinning answer is the private registry mirror (cross-reference the sandbox+PaaS discussion on Zero-install dev: no install command, transparent resolution (Node+Bun) #669).

Closing as completed: the question is answered (no in-process pinning; registry mirror is the path). A future PaaS-mirror implementation would be its own webjs-file-issue task.

[vivek7405]

CORRECTION: it IS possible, via an onLoad specifier-rewrite (not onResolve)

The earlier conclusion ("no in-process way to pin") was wrong about the available mechanisms. Bun supports INLINE versions in a specifier (import { z } from 'zod@3.22.4'), and auto-install HONORS the inline version. onResolve is bypassed for auto-install, but onLoad (which transforms file source, and which webjs already uses for TS-strip) can rewrite a bare specifier to an inline-versioned one read from package.json. Bun then auto-installs the pinned version.

Verified in a clean Bun 1.3.11 sprite:

• E (inline versions pin): import('zod@3.22.4/package.json') resolved to 3.22.4 (E_INLINE=3.22.4). So a versioned specifier pins, even under zero-install.
• F (the working hack): a --preload onLoad plugin read package.json, rewrote from 'zod' / import('zod/...') to zod@3.22.4 for every declared dep, and a file with a BARE import('zod/package.json') then resolved to 3.22.4 (F_VERSION=3.22.4). The rewritten source was confirmed (REWRITTEN_SRC=...'zod@3.22.4/package.json'...).

So: an onLoad transform that maps bare imports of declared deps to <name>@<version-from-package.json> makes a zero-install Bun app run its PINNED versions instead of latest. This is the version-respecting zero-install mechanism.

Caveats for the implementation (not blockers, but get them right)

• Use Bun's transpiler/AST, not a regex. The spike used a string replace, which is fragile (it would touch strings, comments, dynamic specifiers, re-exports). A real implementation should rewrite import specifiers via the parsed module, not text.
• Direct deps vs transitive. The rewrite pins the APP's DIRECT imports (the package.json deps). A pinned direct dep (e.g. zod@3.22.4) then brings its own dependency subtree resolved from ITS manifest, so transitive deps follow the pinned direct deps. Confirm this holds (that auto-installing zod@3.22.4 resolves zod's subtree deterministically, not each transitive at latest).
• bun.lock for exact pins. package.json carries ranges (^0.7.0); reading the resolved exact version from bun.lock (when present) would pin more precisely than the range floor.
• Minor quirk seen: a BARE import('zod/...') placed AFTER an inline import('zod@3.22.4/...') in the SAME file ENOENT'd in test E (likely a same-file dual-resolution edge); the rewrite avoids this by making every specifier versioned.

Impact

• Reopens the path for bun create defaults to no install (zero-install onboarding); node unchanged #682 (default bun create to --no-install): with the rewrite pinning versions, the zero-install default is SAFE (no unpinned-latest hazard). File the rewrite first, then revisit bun create defaults to no install (zero-install onboarding); node unchanged #682.
• docs: correct #675 zero-install caveat (Bun runs latest, ignores package.json + bun.lock) #683 (the "runs latest" doc caveat) stays accurate UNTIL the rewrite ships, then it should be updated to "pins from package.json".
• Implementation is its own task: extend webjs's Bun onLoad plugin to rewrite declared-dep specifiers to inline-versioned from package.json/bun.lock (filed separately).

Credit: the inline-version idea came from the owner; it is what the onResolve dead-end missed.