#Browser API

@rspack/browser is a version of Rspack specifically designed for browser environments, without relying on WebContainers or any particular platform. Its API is consistent with the JavaScript API of @rspack/core, while additionally providing features and interfaces tailored for the browser environment.

Welcome to try running Rspack in the browser at the Rspack Playground.

#Basic example

The following example demonstrates the basic usage of @rspack/browser. Except for the additional APIs used to read and write project files and outputs, other APIs are consistent with the JavaScript API of @rspack/core.

import { rspack, builtinMemFs } from '@rspack/browser';

// Write files to memfs
builtinMemFs.volume.fromJSON({
  // ...project files
});

rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Get output from memfs after bundling
  const files = builtinMemFs.volume.toJSON();
});

#Response header settings

Note that @rspack/browser internally uses SharedArrayBuffer to implement shared memory across multiple threads. Therefore, you need to set response headers for both your development server and production deployment environment.

If you are using Rspack as your project's bundler, you can set it through devServer.headers:

export default {
  devServer: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};

If you are using Rsbuild as your project's bundler, you can set it through server.headers:

export default {
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};

For production environments, please refer to the documentation of your project's deployment platform.

#In-Memory File system

Since browsers cannot directly access the local file system, @rspack/browser provides an in-memory file system object builtinMemFs based on memfs for reading and writing files in the browser environment. All file system reads and writes in both the Node.js and Rust sides are redirected to this in-memory file system, including reading project configuration, source code, node_modules dependencies, and writing output files.

Here is a basic usage example. For the full API, please refer to the memfs documentation:

import { builtinMemFs } from '@rspack/browser';

// Write files to memfs
builtinMemFs.volume.fromJSON({
  // ...project files
});

// Read files from memfs
const files = builtinMemFs.volume.toJSON();

#Browser-Specific Plugins

To better meet the bundling needs in browser environments, @rspack/browser offers several dedicated plugins.

#BrowserHttpImportEsmPlugin

In local development, developers usually download project dependencies via package managers and store them in the node_modules directory at the root of the project. When using @rspack/browser, you can pre-write dependencies into the node_modules directory within the in-memory file system. However, when the modules your project depends on are uncertain (e.g., allowing users to freely choose third-party dependencies), pre-writing all dependencies becomes impractical.

import { builtinMemFs } from '@rspack/browser';

builtinMemFs.volume.fromJSON({
  '/node_modules/react/index.js': '...',
});

@rspack/browser provides the BrowserHttpImportEsmPlugin plugin. This plugin rewrites third-party dependency module specifiers to URLs of ESM CDNs during module resolution. For example, import React from "react" will be rewritten as import React from "https://esm.sh/react". Together with Rspack's buildHttp feature, dependencies can be dynamically loaded over HTTP during bundling.

import { BrowserHttpImportEsmPlugin } from '@rspack/browser';

export default {
  plugins: [new BrowserHttpImportEsmPlugin({ domain: 'https://esm.sh' })],
  experiments: {
    buildHttp: {
      allowedUris: ['https://'],
    },
  },
};

As shown below, BrowserHttpImportEsmPlugin supports options to specify the ESM CDN domain or to specify particular versions or URLs for certain dependencies.

interface BrowserHttpImportPluginOptions {
  /**
   * ESM CDN domain
   */
  domain: string | ((resolvedRequest: ResolvedRequest) => string);
  /**
   * Specify ESM CDN URL for dependencies.
   * If a record is provided, it will be used to map package names to their CDN URLs.
   *
   * Once this function resolves a dependency, other options are ignored.
   */
  dependencyUrl?:
    | Record<string, string | undefined>
    | ((resolvedRequest: ResolvedRequest) => string | undefined);
  /**
   * Specify versions for dependencies.
   * Default to "latest" if not specified.
   */
  dependencyVersions?: Record<string, string | undefined>;
  /**
   * You can attach additional queries supported by the CDN to the `request.url`.
   * For example, to specify the external dependencies under esm.sh, you can do:
   * `request.url.searchParams.set("external", "react,react-dom")`
   */
  postprocess?: (request: ProcessedRequest) => void;
}

#BrowserRequirePlugin

In Rspack, certain scenarios require dynamically loading and executing JavaScript code, such as Loaders or the template functions of HtmlRspackPlugin. Since this code may come from untrusted users, executing it directly in the browser environment poses potential security risks. To ensure safety, @rspack/browser throws errors by default in such cases to prevent unsafe code execution.

The BrowserRequirePlugin plugin enables this capability:

import { BrowserRequirePlugin } from '@rspack/browser';

export default {
  plugins: [
    new BrowserRequirePlugin({ execute: BrowserRequirePlugin.unsafeExecute }),
  ],
};

You need to provide an execute function to dynamically run and load CommonJS modules and modify runtime.module.exports to set the module's exports. @rspack/browser provides an unsafe implementation BrowserRequirePlugin.unsafeExecute that internally uses new Function to execute code. You can also implement a safer version based on this API according to your needs, for example:

function safeExecute(code: string, runtime: CommonJsRuntime) {
  const safeCode = sanitizeCode(code);
  BrowserRequirePlugin.unsafeExecute(safeCode, runtime);
}

function uselessExecute(_code: string, runtime: CommonJsRuntime) {
  runtime.module.exports.hello = 'rspack';
}

Options for BrowserRequirePlugin are as follows:

/**
 * Runtime context for loading CommonJS modules
 */
interface CommonJsRuntime {
  module: any;
  exports: any;
  require: BrowserRequire;
}

interface BrowserRequirePluginOptions {
  /**
   * Function to execute dynamic code
   */
  execute: (code: string, runtime: CommonJsRuntime) => void;
}

#Using Module Federation

@rspack/browser supports Rspack's ModuleFederationPlugin. With this feature, you can pre-bundle complex dependency modules as provider projects deployed to CDN, and then use them in consumer projects that are bundled online in the browser.

When using ModuleFederationPlugin in the browser, please note the following:

1. You need to enable the BrowserHttpImportEsmPlugin plugin, as module federation needs to load its runtime dependencies. The CDN needs to provide the development version of @module-federation/webpack-bundler-runtime (Magic Comments in the output shouldn't be removed).
2. Shared modules set in ModuleFederationPlugin also need to be configured with external and specified versions in BrowserHttpImportEsmPlugin. If you're using esm.sh as CDN, you can refer to the following code:

new rspack.BrowserHttpImportEsmPlugin({
  domain: "https://esm.sh",
  dependencyVersions: {
    "react": "19.1.1"
  },
  postprocess: (request) => {
    // Set the `dev` parameter for `react-dom` here as well, as you need to ensure that the provider and consumer projects use the same mode of `react` and `react-dom`.
    if (request.packageName === "@module-federation/webpack-bundler-runtime" || request.packageName === "react-dom") {
      request.url.searchParams.set("dev", "");
    }
    request.url.searchParams.set("external", "react");
  }
}),

3. All ModuleFederationPlugin.shared configurations must set import: false, meaning that consumer projects bundled online cannot bundle shared modules themselves; shared modules must be provided by pre-bundled provider projects.
4. ModuleFederationPlugin.implementation option is not supported.