Browser Metro Bundler

Common errors

• Error: Module not found: Can't resolve 'some-module' in '/path/to/file.ts'

  cause The bundler could not locate the imported module. This often happens due to incorrect import paths, missing files in the `VirtualFS`, or an unconfigured `sourceExts` for the module type.
  fix Verify the import path is correct and the module exists in the `VirtualFS`. Ensure `resolver.sourceExts` in your `BundlerConfig` includes the file extension of the module (e.g., `['ts', 'tsx', 'js', 'jsx']`). If importing an npm package, check network connectivity to your `packageServerUrl` and that the package exists on the remote server.

• TypeError: transformer is not a function

  cause The `transformer` option in `BundlerConfig` was not correctly provided or is not a valid transformer function (e.g., `typescriptTransformer` or `reactRefreshTransformer`).
  fix Ensure you are importing and passing a valid transformer, such as `typescriptTransformer` or `reactRefreshTransformer`, to your `BundlerConfig`. If creating a custom transformer, it must adhere to the `Transformer` interface specified by `browser-metro`.

• React Refresh: A wild runtime error occurred. (or similar HMR-related console errors)

  cause React Refresh typically fails when components are not exportable (e.g., default exports of anonymous functions), or when there are issues with multiple instances of React/React Refresh, or problems with the HMR update application logic on the client side.
  fix Ensure all React components are named exports or default exports of named functions. Verify your HMR client-side logic correctly processes `hmrUpdate` objects from `IncrementalBundler` and applies patches to the iframe or target environment. Check for duplicate React installations if possible.

Warnings

• gotcha Performance for large projects can be a bottleneck. As `browser-metro` runs entirely client-side, bundling extremely large or complex codebases may lead to noticeable performance degradation, especially on less powerful devices or older browsers.
  Fix: Optimize your virtual file system content, use smaller entry points, and consider pre-bundling external dependencies if feasible. Leveraging Web Workers for the bundling process (as `browser-metro` itself does) can mitigate some impact. Monitor bundle size and parsing times.
• gotcha `browser-metro` relies on an external ESM package server (e.g., `https://esm.reactnative.run`) for resolving and bundling npm packages. Downtime, network issues, or rate limiting from this service can prevent package resolution and bundling.
  Fix: Ensure network connectivity to the configured `packageServerUrl`. For critical applications or offline usage, consider self-hosting an ESM package server or pre-packaging essential npm dependencies directly into your `VirtualFS`.
• gotcha Correctly configuring HMR and React Refresh requires careful setup. Incorrect transformer choices (e.g., not using `reactRefreshTransformer`) or improper client-side handling of HMR updates will prevent hot updates and lead to full page reloads.
  Fix: For HMR with React Refresh, use `IncrementalBundler`, specify `reactRefreshTransformer` in your config, and enable `hmr: { enabled: true, reactRefresh: true }`. Ensure your application's runtime correctly receives and applies the `hmrUpdate` objects (e.g., via `iframe.postMessage`) and that React components follow Fast Refresh rules (e.g., named exports).

Install

• npm install browser-metro npm
• yarn add browser-metro yarn
• pnpm add browser-metro pnpm

Imports

• Bundler
  wrong:

  import Bundler from 'browser-metro'; // Not a default export

  correct:

  import { Bundler } from 'browser-metro';

  Bundler is a named export. It is used for one-shot bundling.
• IncrementalBundler
  wrong:

  const IncrementalBundler = require('browser-metro').IncrementalBundler; // Primarily ESM-focused

  correct:

  import { IncrementalBundler } from 'browser-metro';

  Used for watch-mode and HMR-enabled bundling. Ensure your environment supports ESM.
• VirtualFS
  wrong:

  import { Fs as VirtualFS } from 'browser-metro'; // Incorrect alias

  correct:

  import { VirtualFS } from 'browser-metro';

  Provides an in-memory file system abstraction required by the bundler.
• typescriptTransformer
  wrong:

  import { tsTransformer } from 'browser-metro';

  correct:

  import { typescriptTransformer } from 'browser-metro';

  Pre-configured transformer for TypeScript and JSX compilation using Sucrase.
• BundlerConfig

  import type { BundlerConfig } from 'browser-metro';

  This is a TypeScript type definition, typically imported with `import type`.

Quickstart

This quickstart demonstrates how to set up a basic `Bundler` with a `VirtualFS` to bundle TypeScript code, including a dependency. It outputs the resulting self-executing JavaScript bundle, ready for execution in a browser context. It also highlights the necessary `packageServerUrl` for external npm modules.

import { Bundler, VirtualFS, typescriptTransformer } from "browser-metro";
import type { FileMap } from "browser-metro";

async function initializeBundler() {
  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" }, // Required for npm packages
  });

  try {
    const code = await bundler.bundle("/index.ts");
    console.log("Bundled Code:\n", code);
    // To execute in browser context, you might create a Blob URL or inject into an iframe
    // const blob = new Blob([code], { type: 'application/javascript' });
    // const url = URL.createObjectURL(blob);
    // const iframe = document.createElement('iframe');
    // iframe.src = url;
    // document.body.appendChild(iframe);
  } catch (error) {
    console.error("Bundling failed:", error);
  }
}

initializeBundler();