Registry / web-framework / browser-metro

browser-metro

library1.0.15jsnpmunverified

browser-metro is a unique, client-side JavaScript and TypeScript bundler designed to run entirely within a web browser, typically leveraging a Web Worker for performance. Inspired by React Native's Metro bundler, it provides features like Hot Module Replacement (HMR), React Refresh support, and integration with Expo Router for file-based routing. It manages modules through a VirtualFS, performs rapid compilation of TypeScript and JSX via Sucrase transforms, and supports on-demand bundling of npm packages through an external ESM server (e.g., `https://esm.reactnative.run`). As of version 1.0.15, it emphasizes rapid development feedback loops in browser-based playgrounds and development environments. Its key differentiator is its completely client-side operation, removing the need for a Node.js build server for many common development tasks, making it ideal for interactive coding environments and sandboxes.

web-framework devops

npm install browser-metro

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BROWSER-METRO

browser-metro

web-frameworkjavascriptv1.0.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bundler

✓ import { Bundler } from 'browser-metro';

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

Bundler is a named export. It is used for one-shot bundling.

IncrementalBundler

✓ import { IncrementalBundler } from 'browser-metro';

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

Used for watch-mode and HMR-enabled bundling. Ensure your environment supports ESM.

VirtualFS

✓ import { VirtualFS } from 'browser-metro';

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

Provides an in-memory file system abstraction required by the bundler.

typescriptTransformer

✓ import { typescriptTransformer } from 'browser-metro';

✗ import { tsTransformer } 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`.

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();

Debug

Known issues

gotchaPerformance 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.

affects: >=1.0.0

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`.

affects: >=1.0.0

gotchaCorrectly 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).

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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)

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.

Upgrade

Version history

1.0.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/RapidNative/reactnative-run ↗

packagehttps://www.npmjs.com/package/browser-metro ↗

homepagehttps://reactnative.run ↗