browser-metro 1.0.5 → 1.0.7

package/README.md

@@ -0,0 +1,173 @@
+# browser-metro
+
+A browser-based JavaScript/TypeScript bundler inspired by [Metro](https://metrobundler.dev/) (React Native's bundler). It runs entirely client-side in a Web Worker with HMR, React Refresh, Expo Router, and source map support.
+
+Part of [reactnative.run](https://reactnative.run) - try the [playground](https://reactnative.run/playground).
+
+## Features
+
+- **VirtualFS** - in-memory filesystem, no real FS needed
+- **Module resolution** - Node.js-style with configurable extensions
+- **Sucrase transforms** - fast TypeScript/JSX compilation
+- **Plugin system** - pre/post transform hooks, module aliases, shims
+- **HMR** - hot module replacement with React Refresh
+- **Expo Router** - file-based routing with dynamic route HMR
+- **API Routes** - in-browser `+api.ts` via fetch interception
+- **Source maps** - inline combined source maps for accurate errors
+- **npm packages** - on-demand bundling via ESM server
+
+## Install
+
+```bash
+npm install browser-metro
+```
+
+## Quick Start
+
+```typescript
+import {
+  Bundler, VirtualFS, typescriptTransformer
+} from "browser-metro";
+import type { BundlerConfig, FileMap } from "browser-metro";
+
+const files: FileMap = {
+  "/index.ts": 'import { greet } from "./utils";\nconsole.log(greet("World"));',
+  "/utils.ts": 'export function greet(name: string) { return "Hello, " + name; }',
+};
+
+const bundler = new Bundler(new VirtualFS(files), {
+  resolver: { sourceExts: ["ts", "tsx", "js", "jsx"] },
+  transformer: typescriptTransformer,
+  server: { packageServerUrl: "https://esm.reactnative.run" },
+});
+
+const code = await bundler.bundle("/index.ts");
+// code is a self-executing bundle with inline source map
+```
+
+## HMR with React Refresh
+
+```typescript
+import {
+  IncrementalBundler, VirtualFS, reactRefreshTransformer
+} from "browser-metro";
+
+const bundler = new IncrementalBundler(new VirtualFS(files), {
+  resolver: { sourceExts: ["ts", "tsx", "js", "jsx"] },
+  transformer: reactRefreshTransformer,
+  server: { packageServerUrl: "https://esm.reactnative.run" },
+  hmr: { enabled: true, reactRefresh: true },
+});
+
+// Initial build
+const initial = await bundler.build("/index.tsx");
+
+// On file change - only re-transforms changed files
+const result = await bundler.rebuild([
+  { path: "/App.tsx", type: "update" }
+]);
+
+if (result.hmrUpdate && !result.hmrUpdate.requiresReload) {
+  // Send to iframe for hot patching
+  iframe.postMessage({
+    type: "hmr-update",
+    updatedModules: result.hmrUpdate.updatedModules,
+    removedModules: result.hmrUpdate.removedModules,
+  });
+}
+```
+
+## API
+
+### Bundler
+
+One-shot bundler. Creates a single bundle from an entry file.
+
+```typescript
+const bundler = new Bundler(vfs, config);
+const code = await bundler.bundle("/index.ts");
+```
+
+### IncrementalBundler
+
+Watch-mode bundler with HMR. Maintains dependency graph and module cache across rebuilds.
+
+```typescript
+const bundler = new IncrementalBundler(vfs, config);
+const initial = await bundler.build("/index.tsx");
+const update = await bundler.rebuild([{ path: "/App.tsx", type: "update" }]);
+```
+
+### VirtualFS
+
+In-memory filesystem.
+
+```typescript
+const vfs = new VirtualFS(files);
+vfs.read("/index.ts");      // string | undefined
+vfs.write("/new.ts", code);  // create or overwrite
+vfs.exists("/index.ts");     // boolean
+vfs.list();                  // string[]
+```
+
+### BundlerConfig
+
+```typescript
+interface BundlerConfig {
+  resolver: { sourceExts: string[] };
+  transformer: Transformer;
+  server: { packageServerUrl: string };
+  hmr?: { enabled: boolean; reactRefresh?: boolean };
+  plugins?: BundlerPlugin[];
+  env?: Record<string, string>;
+}
+```
+
+### Transformers
+
+- `typescriptTransformer` - TS/JSX via Sucrase
+- `reactRefreshTransformer` - adds React Refresh + `module.hot.accept()`
+- `createReactRefreshTransformer(base)` - wrap a custom transformer with React Refresh
+
+### Plugins
+
+```typescript
+interface BundlerPlugin {
+  name: string;
+  transformSource?(params): { src: string } | null;   // before Sucrase
+  transformOutput?(params): { code: string } | null;   // after Sucrase
+  resolveRequest?(context, name): string | null;       // custom resolution
+  moduleAliases?(): Record<string, string>;            // redirect requires
+  shimModules?(): Record<string, string>;              // inline replacements
+}
+```
+
+## ESM Package Server
+
+browser-metro fetches npm packages from an ESM server that bundles them on-demand with esbuild:
+
+```
+https://esm.reactnative.run/pkg/lodash@4.17.21
+https://esm.reactnative.run/pkg/react-dom@19/client
+```
+
+Packages are cached after first request. All dependencies are externalized for shared runtime instances. Version pinning via `// @externals` metadata prevents transitive dependency mismatches.
+
+## Documentation
+
+Full docs at [reactnative.run/docs](https://reactnative.run/docs):
+
+- [Architecture](https://reactnative.run/docs/architecture)
+- [HMR & React Refresh](https://reactnative.run/docs/hmr)
+- [Expo Router](https://reactnative.run/docs/expo-router)
+- [API Routes](https://reactnative.run/docs/api-routes)
+- [Plugin System](https://reactnative.run/docs/api/plugins)
+- [Full API Reference](https://reactnative.run/docs/api/bundler)
+
+## Author
+
+Built by [Sanket Sahu](https://github.com/sanketsahu) at [RapidNative](https://rapidnative.com).
+
+## License
+
+MIT

package/dist/bundler.d.ts

@@ -5,7 +5,10 @@ export declare class Bundler {
     private resolver;
     private config;
     private plugins;
+    private prefetchedPackages;
     constructor(fs: VirtualFS, config: BundlerConfig);
+    /** Prefetch all dependencies in a single batch request */
+    private prefetchDependencies;
     /** Read tsconfig.json "compilerOptions.paths" from the VirtualFS */
     private static readTsconfigPaths;
     /** Run the full pre-transform -> Sucrase -> post-transform pipeline */

package/dist/bundler.js

@@ -1,14 +1,56 @@
 import { Resolver } from "./resolver.js";
 import { buildCombinedSourceMap, countNewlines, inlineSourceMap, shiftSourceMapOrigLines, } from "./source-map.js";
-import { findRequires, rewriteRequires, buildBundlePreamble } from "./utils.js";
+import { findRequires, rewriteRequires, buildBundlePreamble, parseExternalsFromBody, hashDeps, parseDepBundle } from "./utils.js";
 export class Bundler {
     constructor(fs, config) {
+        this.prefetchedPackages = {};
         this.fs = fs;
         this.config = config;
         const paths = Bundler.readTsconfigPaths(fs);
         this.resolver = new Resolver(fs, { ...config.resolver, ...(paths && { paths }) });
         this.plugins = config.plugins ?? [];
     }
+    /** Prefetch all dependencies in a single batch request */
+    async prefetchDependencies() {
+        const versions = this.getPackageVersions();
+        if (Object.keys(versions).length === 0)
+            return;
+        // Remove aliased and shimmed packages - they're handled client-side
+        const aliases = this.getModuleAliases();
+        const shims = this.getShimModules();
+        for (const name of Object.keys(aliases))
+            delete versions[name];
+        for (const name of Object.keys(shims))
+            delete versions[name];
+        // Also remove alias targets that are already in versions (e.g. react-native-web is fetched via alias)
+        if (Object.keys(versions).length === 0)
+            return;
+        const hash = await hashDeps(versions);
+        const baseUrl = this.config.server.packageServerUrl;
+        try {
+            // Try GET first (CDN cacheable)
+            const getRes = await fetch(`${baseUrl}/bundle-deps/${hash}`);
+            if (getRes.ok) {
+                const { packages } = parseDepBundle(await getRes.text());
+                this.prefetchedPackages = packages;
+                return;
+            }
+            // POST to build
+            const postRes = await fetch(`${baseUrl}/bundle-deps`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ hash, dependencies: versions }),
+            });
+            if (postRes.ok) {
+                const { packages } = parseDepBundle(await postRes.text());
+                this.prefetchedPackages = packages;
+            }
+        }
+        catch (err) {
+            // Silently fall back to individual fetches
+            console.warn("[prefetch] Failed, falling back to individual fetches:", err);
+        }
+    }
     /** Read tsconfig.json "compilerOptions.paths" from the VirtualFS */
     static readTsconfigPaths(fs) {
         const raw = fs.read("/tsconfig.json");
@@ -146,6 +188,21 @@ export class Bundler {
     }
     /** Fetch a pre-bundled npm package from the package server */
     async fetchPackage(specifier) {
+        // Check prefetched registry first (extract base package name from versioned specifier)
+        // specifier is like "react@19.1.0" or "react-dom@19.1.0/client"
+        let baseName = specifier;
+        const atIdx = specifier.indexOf("@", specifier.startsWith("@") ? 1 : 0);
+        if (atIdx > 0) {
+            baseName = specifier.slice(0, atIdx);
+            const afterVersion = specifier.indexOf("/", atIdx + 1);
+            if (afterVersion > 0) {
+                baseName = specifier.slice(0, atIdx) + specifier.slice(afterVersion);
+            }
+        }
+        if (this.prefetchedPackages[baseName]) {
+            return { code: this.prefetchedPackages[baseName], externals: {} };
+        }
+        // Fallback to individual fetch
         const url = this.config.server.packageServerUrl + "/pkg/" + specifier;
         const res = await fetch(url);
         if (!res.ok) {
@@ -153,18 +210,13 @@ export class Bundler {
             throw new Error("Failed to fetch package '" + specifier + "' (HTTP " + res.status + ")" + (body ? ": " + body.slice(0, 200) : ""));
         }
         const code = await res.text();
-        let externals = {};
-        const externalsHeader = res.headers.get("X-Externals");
-        if (externalsHeader) {
-            try {
-                externals = JSON.parse(externalsHeader);
-            }
-            catch { }
-        }
+        const externals = parseExternalsFromBody(code);
         return { code, externals };
     }
     /** Build the module map by walking the dependency graph */
     async buildModuleMap(entryFile) {
+        // Prefetch all deps in a single batch request
+        await this.prefetchDependencies();
         const moduleMap = {};
         const sourceMapMap = {};
         const visited = {};
@@ -187,7 +239,7 @@ export class Bundler {
                 return;
             }
             const source = this.fs.read(filePath);
-            if (!source) {
+            if (source === undefined) {
                 throw new Error("File not found: " + filePath);
             }
             // Transform the file (TS -> JS, JSX -> JS, etc.)

package/dist/incremental-bundler.d.ts

@@ -14,6 +14,7 @@ export declare class IncrementalBundler {
     private entryFile;
     private packageVersions;
     private transitiveDepsVersions;
+    private prefetchedPackages;
     constructor(fs: VirtualFS, config: BundlerConfig);
     /** Read tsconfig.json "compilerOptions.paths" from the VirtualFS */
     private static readTsconfigPaths;
@@ -34,6 +35,8 @@ export declare class IncrementalBundler {
     /** Resolve an npm specifier to a versioned form.
      *  Priority: user's package.json > transitive dep versions from manifests > bare name */
     private resolveNpmSpecifier;
+    /** Prefetch all dependencies in a single batch request */
+    private prefetchDependencies;
     /** Fetch a pre-bundled npm package from the package server */
     private fetchPackage;
     /**

package/dist/incremental-bundler.js

@@ -3,7 +3,7 @@ import { DependencyGraph } from "./dependency-graph.js";
 import { ModuleCache } from "./module-cache.js";
 import { emitHmrBundle, HMR_RUNTIME_TEMPLATE } from "./hmr-runtime.js";
 import { buildCombinedSourceMap, countNewlines, inlineSourceMap, shiftSourceMapOrigLines, } from "./source-map.js";
-import { findRequires, rewriteRequires, hashString, buildBundlePreamble } from "./utils.js";
+import { findRequires, rewriteRequires, hashString, buildBundlePreamble, parseExternalsFromBody, hashDeps, parseDepBundle } from "./utils.js";
 export class IncrementalBundler {
     constructor(fs, config) {
         this.graph = new DependencyGraph();
@@ -13,6 +13,7 @@ export class IncrementalBundler {
         this.entryFile = null;
         this.packageVersions = {};
         this.transitiveDepsVersions = {};
+        this.prefetchedPackages = {};
         this.fs = fs;
         this.config = config;
         const paths = IncrementalBundler.readTsconfigPaths(fs);
@@ -162,8 +163,61 @@ export class IncrementalBundler {
         const subpath = specifier.slice(baseName.length);
         return baseName + "@" + version + subpath;
     }
+    /** Prefetch all dependencies in a single batch request */
+    async prefetchDependencies() {
+        if (Object.keys(this.prefetchedPackages).length > 0)
+            return; // already prefetched
+        const versions = { ...this.packageVersions };
+        if (Object.keys(versions).length === 0)
+            return;
+        // Remove aliased and shimmed packages - they're handled client-side
+        const aliases = this.getModuleAliases();
+        const shims = this.getShimModules();
+        for (const name of Object.keys(aliases))
+            delete versions[name];
+        for (const name of Object.keys(shims))
+            delete versions[name];
+        if (Object.keys(versions).length === 0)
+            return;
+        const hash = await hashDeps(versions);
+        const baseUrl = this.config.server.packageServerUrl;
+        try {
+            const getRes = await fetch(`${baseUrl}/bundle-deps/${hash}`);
+            if (getRes.ok) {
+                const { packages } = parseDepBundle(await getRes.text());
+                this.prefetchedPackages = packages;
+                return;
+            }
+            const postRes = await fetch(`${baseUrl}/bundle-deps`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ hash, dependencies: versions }),
+            });
+            if (postRes.ok) {
+                const { packages } = parseDepBundle(await postRes.text());
+                this.prefetchedPackages = packages;
+            }
+        }
+        catch (err) {
+            console.warn("[prefetch] Failed, falling back to individual fetches:", err);
+        }
+    }
     /** Fetch a pre-bundled npm package from the package server */
     async fetchPackage(specifier) {
+        // Check prefetched registry first
+        let baseName = specifier;
+        const atIdx = specifier.indexOf("@", specifier.startsWith("@") ? 1 : 0);
+        if (atIdx > 0) {
+            baseName = specifier.slice(0, atIdx);
+            const afterVersion = specifier.indexOf("/", atIdx + 1);
+            if (afterVersion > 0) {
+                baseName = specifier.slice(0, atIdx) + specifier.slice(afterVersion);
+            }
+        }
+        if (this.prefetchedPackages[baseName]) {
+            return { code: this.prefetchedPackages[baseName], externals: {} };
+        }
+        // Fallback to individual fetch
         const url = this.config.server.packageServerUrl + "/pkg/" + specifier;
         const res = await fetch(url);
         if (!res.ok) {
@@ -171,14 +225,7 @@ export class IncrementalBundler {
             throw new Error("Failed to fetch package '" + specifier + "' (HTTP " + res.status + ")" + (body ? ": " + body.slice(0, 200) : ""));
         }
         const code = await res.text();
-        let externals = {};
-        const externalsHeader = res.headers.get("X-Externals");
-        if (externalsHeader) {
-            try {
-                externals = JSON.parse(externalsHeader);
-            }
-            catch { }
-        }
+        const externals = parseExternalsFromBody(code);
         return { code, externals };
     }
     /**
@@ -198,7 +245,7 @@ export class IncrementalBundler {
             return { localDeps: [], npmDeps: [] };
         }
         const source = this.fs.read(filePath);
-        if (!source) {
+        if (source === undefined) {
             throw new Error("File not found: " + filePath);
         }
         const sourceHash = hashString(source);
@@ -394,6 +441,8 @@ export class IncrementalBundler {
         this.moduleMap = {};
         this.sourceMapMap = {};
         this.packageVersions = this.getPackageVersions();
+        // Prefetch all deps in a single batch request
+        await this.prefetchDependencies();
         const npmPackagesNeeded = new Set();
         this.walkDeps(entryFile, npmPackagesNeeded);
         // Process module aliases: swap sources for targets in the fetch list

package/dist/utils.d.ts

@@ -1,3 +1,7 @@
+/** Parse externals metadata from a package bundle body.
+ *  Looks for a `// @externals {...}` comment line near the top.
+ *  Falls back to empty object if not found. */
+export declare function parseExternalsFromBody(code: string): Record<string, string>;
 /** Extract all require('...') call targets from source */
 export declare function findRequires(source: string): string[];
 /**
@@ -29,3 +33,14 @@ export declare function buildBundlePreamble(env?: Record<string, string>, router
 export declare function buildRouterShim(): string;
 /** Fast djb2 hash for cache invalidation */
 export declare function hashString(str: string): string;
+/** Hash a dependencies object to a stable cache key.
+ *  Uses SHA-256 (via Web Crypto or Node crypto) truncated to 16 hex chars
+ *  for collision resistance while keeping URLs short.
+ *  Includes a version prefix so cache is invalidated when bundling logic changes. */
+export declare function hashDeps(deps: Record<string, string>): Promise<string>;
+/** Parse a dep bundle response into individual package code chunks.
+ *  Format: `// @dep-start <name>\n..code..\n// @dep-end <name>` */
+export declare function parseDepBundle(code: string): {
+    manifest: Record<string, string>;
+    packages: Record<string, string>;
+};

package/dist/utils.js

@@ -1,6 +1,24 @@
 const REQUIRE_RE = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
 // Matches lines that are single-line comments or JSDoc/block comment continuations
 const COMMENT_LINE_RE = /^\s*(?:\/\/|\/?\*)/;
+const EXTERNALS_RE = /^\/\/ @externals (.+)$/m;
+const DEP_MANIFEST_RE = /^\/\/ @dep-manifest (.+)$/m;
+const DEP_START_RE = /^\/\/ @dep-start (.+)$/gm;
+const DEP_END_RE = /^\/\/ @dep-end (.+)$/gm;
+/** Parse externals metadata from a package bundle body.
+ *  Looks for a `// @externals {...}` comment line near the top.
+ *  Falls back to empty object if not found. */
+export function parseExternalsFromBody(code) {
+    const match = EXTERNALS_RE.exec(code);
+    if (!match)
+        return {};
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return {};
+    }
+}
 /** Extract all require('...') call targets from source */
 export function findRequires(source) {
     if (!source)
@@ -206,3 +224,47 @@ export function hashString(str) {
     }
     return (hash >>> 0).toString(36);
 }
+// Must match SERVER_VERSION in reactnative-esm/src/index.ts
+const DEPS_HASH_VERSION = "2";
+/** Hash a dependencies object to a stable cache key.
+ *  Uses SHA-256 (via Web Crypto or Node crypto) truncated to 16 hex chars
+ *  for collision resistance while keeping URLs short.
+ *  Includes a version prefix so cache is invalidated when bundling logic changes. */
+export async function hashDeps(deps) {
+    const sorted = Object.keys(deps).sort().map(k => `${k}@${deps[k]}`).join(",");
+    const input = `v${DEPS_HASH_VERSION}:${sorted}`;
+    // Web Crypto API (works in browsers and workers)
+    if (typeof globalThis.crypto?.subtle?.digest === "function") {
+        const data = new TextEncoder().encode(input);
+        const buf = await crypto.subtle.digest("SHA-256", data);
+        const arr = Array.from(new Uint8Array(buf));
+        return arr.map(b => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
+    }
+    // Fallback: djb2 (Node.js without crypto, shouldn't normally happen)
+    return hashString(input);
+}
+/** Parse a dep bundle response into individual package code chunks.
+ *  Format: `// @dep-start <name>\n..code..\n// @dep-end <name>` */
+export function parseDepBundle(code) {
+    let manifest = {};
+    const manifestMatch = DEP_MANIFEST_RE.exec(code);
+    if (manifestMatch) {
+        try {
+            manifest = JSON.parse(manifestMatch[1]);
+        }
+        catch { }
+    }
+    const packages = {};
+    const startRe = /^\/\/ @dep-start (.+)$/gm;
+    let match;
+    while ((match = startRe.exec(code)) !== null) {
+        const name = match[1];
+        const startIdx = match.index + match[0].length + 1; // skip newline
+        const endMarker = `// @dep-end ${name}`;
+        const endIdx = code.indexOf(endMarker, startIdx);
+        if (endIdx !== -1) {
+            packages[name] = code.slice(startIdx, endIdx).trimEnd();
+        }
+    }
+    return { manifest, packages };
+}

package/package.json

@@ -1,12 +1,29 @@
 {
   "name": "browser-metro",
-  "version": "1.0.5",
-  "description": "A browser-based JavaScript/TypeScript bundler with HMR support",
+  "version": "1.0.7",
+  "description": "A browser-based JavaScript/TypeScript bundler with HMR support, inspired by Metro. Runs entirely client-side.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
+  "keywords": [
+    "bundler",
+    "react-native",
+    "metro",
+    "hmr",
+    "typescript",
+    "jsx",
+    "browser",
+    "virtual-fs",
+    "expo-router"
+  ],
+  "homepage": "https://reactnative.run",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RapidNative/reactnative-run"
+  },
+  "author": "Sanket Sahu <sanket@rapidnative.com> (https://github.com/sanketsahu)",
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",