#output.externals

• Type:

type Externals =
  | string
  | object
  | function
  | RegExp
  | Array<string | object | function | RegExp>;

• Default: undefined

Use this option to specify which modules should not be bundled by Rsbuild, and instead use implementations provided by the external environment.

For example, if your page already loads React from a CDN, or if you're building a library and want consumers to install react themselves, you can declare it as an external. This reduces bundle size and avoids including the same dependency twice.

This is commonly used in library development, and is also useful in app scenarios such as loading dependencies from a CDN or relying on dependencies injected by the host environment.

For more details, see the Rspack Externals documentation.

#Examples

#Basic usage

For example, you can exclude react-dom from the output bundle and access the module at runtime through the global ReactDOM variable:

export default {
  output: {
    externals: {
      'react-dom': 'ReactDOM',
      'react-dom/client': 'ReactDOM',
    },
  },
};

Note that string matching for module names is exact. That means you need to explicitly declare subpath imports such as react-dom/client.

If you need to match a group of similar import patterns, use regular expressions or a function for more flexible matching logic.

#Array format

Use an array to define multiple external configurations:

export default {
  output: {
    externals: [
      {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      'lodash',
    ],
  },
};

#Using with CDN

A common use case is to load libraries from CDN and exclude them from your bundle, then use html.tags to include them in your HTML.

export default {
  output: {
    externals: {
      axios: 'axios',
    },
  },
  html: {
    tags: [
      {
        tag: 'script',
        append: false,
        attrs: {
          defer: true,
          crossorigin: true,
          src: 'https://unpkg.com/axios@1/dist/axios.min.js',
        },
      },
    ],
  },
};

Then you can use the external libraries in your source code:

const response = await window.axios.get('/api/users');

#Regular expressions

Use regular expressions to match multiple modules with a pattern:

export default {
  output: {
    externals: [
      // Externalize all @babel packages
      /^@babel\/.+$/,
      // Externalize all lodash sub-modules
      /^lodash\/.+$/,
    ],
  },
};

#Web workers

When building a worker with output.target set to web-worker, external dependencies must be available in the worker itself. Workers cannot access global variables from the host page.

For module worker output (output.module is true), external dependencies are loaded through ES module imports by default. Make sure the worker runtime can resolve the external module paths.

For classic worker output (output.module: false), you can map dependencies to global variables in the worker. For example, map worker-sdk to self.WorkerSDK:

export default {
  output: {
    target: 'web-worker',
    module: false,
    externals: {
      'worker-sdk': 'self WorkerSDK',
    },
  },
};

Before loading the worker bundle, load a script that defines self.WorkerSDK. For example, use a separate bootstrap script that calls importScripts() to load the dependency script first, then the worker bundle.