close
Guide
Config
Plugin
API
Blog
About
Contribute
Guide
Config
Plugin
API
Blog
About
Contribute

CssExtractRspackPlugin

Rspack only

Rspack is currently incompatible with mini-css-extract-plugin, but you can use the CssExtractRspackPlugin as a replacement. It can be used with css-loader to extract CSS into separate files.

If your project does not depend on on css-loader and mini-css-extract-plugin, it is recommended to use Rspack's built-in CSS solution experiments.css, which offers better performance.

Example

When using CssExtractRspackPlugin, you need to register the plugin in the plugins section and register CssExtractRspackPlugin.loader in module.rules.

rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};

Plugin Options

Options for CssExtractRspackPlugin.

  • Types:
interface PluginOptions {
  filename?: string | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  chunkFilename?:
    | string
    | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  ignoreOrder?: boolean;
  insert?: string | ((linkTag: HTMLLinkElement) => void);
  attributes?: Record<string, string>;
  linkType?: string | 'text/css' | false;
  runtime?: boolean;
  pathinfo?: boolean;
}
NameTypeDefault ValueDescription
filenamestring"[name].css"The name of each CSS output file, please refer to output.filename
chunkFilenamestring"[name].css"The name of the asynchronously loaded CSS files. If not set, it will use filename; please refer to output.chunkFilename
ignoreOrderbooleanfalseWhether to issue a warning if there are conflicts in the order of some CSS in different chunks. For example, entryA introduces a.css and b.css, entryB introduces b.css and a.css, and the order of a.css and b.css cannot be determined
insertstring | ((linkTag: HTMLLinkElement) => void)undefinedDecide how the link tag is inserted into the page. If passed as a string type, it will be regarded as DOM selector, and the link tag will be inserted after element corresponding to that selector. If passed as function type, the function will be converted into a string at runtime for invocation, with link tag as parameter
attributesRecord<string, string>undefinedAdds custom attributes to the link tag for async CSS chunks
linkTypestring | 'text/css' | false"text/css"Set the type attribute value for link tags to load async CSS chunks
runtimebooleantrueWhether to inject runtime code for CSS loading. If disabled, CSS will be still extracted and can be used for a custom loading methods
pathinfobooleanfalseWhether to include comments in CSS bundles with more detailed path information

Loader Options

Options for CssExtractRspackPlugin.loader.

  • Types:
interface LoaderOptions {
  publicPath?: string | ((resourcePath: string, context: string) => string);
  emit?: boolean;
  esModule?: boolean;
}
NameTypeDefault ValueDescription
publicPathstring | ((resourcePath: string, context: string) => string)output.publicPathSpecifies a custom public path for the external resources like images, files, etc inside CSS
emitbooleantrueIf true, emits CSS files. If false, the plugin will extract the CSS but will not emit files
esModulebooleantruewhether to use ES module syntax for CSS Modules class name exports in the generated JavaScript module

Note

Please note when enabling the built-in CSS support (experiments.css), Files ending with .css will be automatically treated as css/auto modules. If you want to use this plugin, make sure that the rule types with CssExtractRspackPlugin.loader set are all overridden by javascript/auto instead of the default css/auto.

For example:

rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /src\/legacy-project\/.*\.css$/,
        type: 'javascript/auto', // Cover the default CSS module type and treat it as a regular JS file.
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
      {
        test: /src\/new-project\/.*\.css$/,
        type: 'css/auto', // Handle with built-in CSS
      },
    ],
  },
  experiments: {
    css: true,
  },
};