#output.autoExternal

• Type:

type AutoExternal =
  | boolean
  | {
      dependencies?: boolean;
      optionalDependencies?: boolean;
      devDependencies?: boolean;
      peerDependencies?: boolean;
    };

• Default: false

Automatically externalize dependencies declared in the root package.json. When enabled, Rsbuild reads the dependency fields from <root>/package.json and converts the matched package names into output.externals rules.

This is useful for Node.js or SSR bundles where some dependencies should be loaded by the runtime instead of being bundled, such as observability SDKs, native addons, or dependencies that rely on runtime instrumentation.

#Default behavior

When output.autoExternal is true, the following dependency types are externalized by default:

• dependencies
• optionalDependencies
• peerDependencies

The following dependency type is not externalized by default:

• devDependencies

This is equivalent to the following configuration:

export default {
  output: {
    autoExternal: {
      dependencies: true,
      optionalDependencies: true,
      peerDependencies: true,
      devDependencies: false,
    },
  },
};

#Subpath imports

Rsbuild also externalizes subpath imports of matched dependencies. For example, if react is declared in dependencies, both of the following imports will be externalized:

import React from 'react';
import { jsx } from 'react/jsx-runtime';

#Examples

#Enable auto externalization

export default {
  output: {
    target: 'node',
    autoExternal: true,
  },
};

#Customize dependency types

export default {
  output: {
    target: 'node',
    autoExternal: {
      dependencies: true,
      optionalDependencies: true,
      peerDependencies: true,
      devDependencies: true,
    },
  },
};

#Disable a dependency type

export default {
  output: {
    target: 'node',
    autoExternal: {
      peerDependencies: false,
    },
  },
};

#Relationship with output.externals

output.externals has higher priority than output.autoExternal. You can use output.externals to manually customize the external format for specific packages, and use output.autoExternal to handle the remaining dependencies from package.json.

export default {
  output: {
    target: 'node',
    externals: {
      react: 'react-18',
    },
    autoExternal: true,
  },
};

In the example above, react follows the manual output.externals configuration instead of the automatically generated rule.

When output.externals is configured as an object, Rsbuild skips the auto externalization rules for package names that appear as object keys. For example, if you configure react in output.externals, Rsbuild will not generate auto externalization rules for react or its subpath imports, such as react/jsx-runtime. If you want these subpath imports to remain externalized, you need to add them to output.externals as well.

For more complex output.externals configurations, such as arrays, functions, or regular expressions, Rsbuild merges them with the rules generated by output.autoExternal. If the final behavior does not match your expectation, you can use DEBUG=rsbuild or rsbuild inspect to view the effective externals configuration.