ContextQMD
Back to Rspack

Module generator

website/docs/en/config/module-generator.mdx

2.0.521.8 KB
Original Source

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.docschina.org/configuration/module/" />

Module generator

module.generator controls how Rspack turns parsed modules into output code or emitted assets. It affects output-related behavior such as asset filenames, public paths, CSS Modules exports, and other generation settings for each module type.

generator

  • Type: Object
  • Default: {}

Use module.generator to define output generation options for each module type.

Available generator option groups:

js
export default {
  module: {
    generator: {
      // Generator options for asset modules
      asset: {
        dataUrl: {
          encoding: false,
          mimetype: 'image/png',
        },
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for asset/inline modules
      'asset/inline': {
        dataUrl: {
          encoding: false,
          mimetype: 'image/png',
        },
      },
      // Generator options for asset/resource modules
      'asset/resource': {
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for css/auto modules
      'css/auto': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `css` modules
      css: {
        exportsOnly: false,
        esModule: true,
      },
      // Generator options for css/global modules
      'css/global': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for css/module modules
      'css/module': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `json` modules
      json: {
        JSONParse: true,
      },
    },
  },
};

asset

Generator options for asset modules.

js
export default {
  module: {
    generator: {
      asset: {
        // options
      },
    },
  },
};

asset.binary

  • Type: boolean | undefined
  • Default: undefined

Whether or not this asset module should be considered binary. This can be set to false to treat this asset module as text. If not set, the module type will be used to determine if the module is binary.

js
export default {
  module: {
    generator: {
      asset: {
        binary: false,
      },
    },
  },
};

asset.dataUrl

  • Type: Object | (source: Buffer, context: { filename: string, module: Module }) => string
  • Default: {}

Only for modules with module type 'asset' or 'asset/inline'.

js
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          encoding: 'base64',
          mimetype: 'image/png',
        },
      },
    },
  },
};

When used as a function, it executes for every module and must return a data URI string.

js
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  module: {
    generator: {
      asset: {
        dataUrl: ({ content }) => {
          const svgToMiniDataURI = require('mini-svg-data-uri');
          return svgToMiniDataURI(content);
        },
      },
    },
  },
};

asset.dataUrl.encoding

  • Type: false | 'base64'
  • Default: 'base64'

When set to 'base64', module source will be encoded using Base64 algorithm. Setting encoding to false will disable encoding. Only for modules with module type 'asset' or 'asset/inline'.

js
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          encoding: false,
        },
      },
    },
  },
};

asset.dataUrl.mimetype

  • Type: string
  • Default: require('mime-types').lookup(ext)

A mimetype for data URI. Resolves from module resource extension by default. Only for modules with module type 'asset' or 'asset/inline'.

js
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          mimetype: 'image/png',
        },
      },
    },
  },
};

asset.importMode

  • Type: 'url' | 'preserve'
  • Default: 'url'

If "url", a URL pointing to the asset will be generated based on publicPath. If "preserve", preserve import/require statement from generated asset.

Only for modules with module type 'asset' or 'asset/resource'.

  • 'asset':
js
export default {
  module: {
    generator: {
      asset: {
        importMode: 'preserve',
      },
    },
  },
};
  • 'asset/resource':
js
export default {
  module: {
    generator: {
      'asset/resource': {
        importMode: 'preserve',
      },
    },
  },
};

asset.filename

  • Type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
  • Default: undefined
  • Supported Template string: see output.assetModuleFilename

Same as output.assetModuleFilename. Overrides output.assetModuleFilename and only works for asset and asset/resource module types.

js
export default {
  module: {
    generator: {
      asset: {
        filename: 'static/[hash][ext]',
      },
    },
  },
};

asset.outputPath

  • Type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
  • Default: undefined

Emit the asset in the specified folder relative to output.path.

Only for modules with module type 'asset' or 'asset/resource'.

js
export default {
  module: {
    generator: {
      asset: {
        outputPath: 'foo/',
      },
    },
  },
};

asset.publicPath

  • Type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
  • Default: undefined

Override output.publicPath, only for modules with module type 'asset' or 'asset/resource'.

js
export default {
  module: {
    generator: {
      asset: {
        publicPath: 'https://cdn.example.com/',
      },
    },
  },
};

asset.emit

  • Type: boolean
  • Default: true

Whether to output assets to disk. You can set this option to false to avoid outputting unnecessary files for some scenarios such as SSR.

Only for modules with module type 'asset' or 'asset/resource'.

  • 'asset':
js
export default {
  module: {
    generator: {
      asset: {
        emit: false,
      },
    },
  },
};
  • 'asset/resource':
js
export default {
  module: {
    generator: {
      'asset/resource': {
        emit: false,
      },
    },
  },
};

["asset/inline"]

Generator options for asset/inline modules.

js
export default {
  module: {
    generator: {
      'asset/inline': {
        // options
      },
    },
  },
};

["asset/inline"].binary

Same as module.generator["asset"].binary.

js
export default {
  module: {
    generator: {
      'asset/inline': {
        binary: false,
      },
    },
  },
};

["asset/inline"].dataUrl

Same as module.generator["asset"].dataUrl.

js
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          // options
        },
      },
    },
  },
};

["asset/inline"].dataUrl.encoding

Same as module.generator["asset"].dataUrl.encoding.

js
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          encoding: false,
        },
      },
    },
  },
};

["asset/inline"].dataUrl.mimetype

Same as module.generator["asset"].dataUrl.mimetype.

js
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          mimetype: 'image/png',
        },
      },
    },
  },
};

["asset/resource"]

Generator options for asset/resource modules.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        // options
      },
    },
  },
};

["asset/resource"].binary

Same as module.generator["asset"].binary.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        binary: false,
      },
    },
  },
};

["asset/resource"].importMode

Same as module.generator["asset"].importMode.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        importMode: 'preserve',
      },
    },
  },
};

["asset/resource"].filename

Same as module.generator["asset"].filename.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        filename: 'static/[hash][ext]',
      },
    },
  },
};

["asset/resource"].outputPath

Same as module.generator["asset"].outputPath.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        outputPath: 'foo/',
      },
    },
  },
};

["asset/resource"].publicPath

Same as module.generator["asset"].publicPath.

js
export default {
  module: {
    generator: {
      'asset/resource': {
        publicPath: 'https://cdn.example.com/',
      },
    },
  },
};

["css/auto"]

Generator options for css/auto modules.

js
export default {
  module: {
    generator: {
      'css/auto': {
        // options
      },
    },
  },
};

["css/auto"].exportsConvention

  • Type: 'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only'
  • Default: 'as-is'

Customize how CSS export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.

js
export default {
  module: {
    generator: {
      'css/auto': {
        exportsConvention: 'camel-case',
      },
    },
  },
};

["css/auto"].exportsOnly

  • Type: boolean
  • Default: true when the target has no document support, otherwise false.

If true, only exports the identifier mappings from CSS into the output JavaScript files, without embedding any stylesheets in the template. Useful if you are using CSS Modules for pre-rendering (e.g. SSR).

If false, generate stylesheets and embed them in the template.

js
export default {
  module: {
    generator: {
      'css/auto': {
        exportsOnly: false,
      },
    },
  },
};

["css/auto"].localIdentName

  • Type: string
  • Default: [uniqueName]-[id]-[local] in development mode when output.uniqueName is non-empty, [id]-[local] in development mode otherwise, and [fullhash] in production mode.

Customize the format of the local class names generated for CSS modules, besides the substitutions at File-level and Module-level, also include [uniqueName] and [local].

js
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};

["css/auto"].localIdentHashDigest

  • Type: string
  • Default: 'base64url'

Configure the digest encoding used for hashes in generated CSS Modules local identifiers. This has the same supported values as output.hashDigest.

js
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};

["css/auto"].localIdentHashDigestLength

  • Type: number
  • Default: 6

Configure how many characters from the hash are used in generated CSS Modules local identifiers.

js
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};

["css/auto"].localIdentHashFunction

Configure the hash function used for generated CSS Modules local identifiers. This has the same supported values as output.hashFunction.

js
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};

["css/auto"].localIdentHashSalt

Configure a salt added to the hash used for generated CSS Modules local identifiers. When unset, Rspack uses output.hashSalt.

js
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};

["css/auto"].esModule

  • Type: boolean
  • Default: true

This configuration is available for improved ESM-CJS interoperability purposes.

Whether to add __esModule to the exports of CSS; if added, it will be treated as ES modules during ESM-CJS interop, otherwise, it will be treated as a CommonJS Module.

js
export default {
  module: {
    generator: {
      'css/auto': {
        esModule: true,
      },
    },
  },
};

For example, a common use case, when using the CommonJS output from a third-party component library, it is sometimes necessary to add this configuration to ensure correct ESM-CJS interop, to obtain the correct exports (this can be used in conjunction with rules[].test and other matching conditions to add it only for that particular component library).

The original source code of the third-party component library:

js
import style from './style.css';

export function Button() {
  return <button className={style.btn}></button>;
}

The CommonJS format output published by the third-party component library:

js
'use strict';

Object.defineProperty(exports, '__esModule', {
  value: true,
});
exports.Button = Button;
var _style = _interopRequireDefault(require('./style.css'));
var _jsxRuntime = require('react/jsx-runtime');
function _interopRequireDefault(obj) {
  return obj && obj.__esModule ? obj : { default: obj };
}
function Button() {
  return /*#__PURE__*/ (0, _jsxRuntime.jsx)('button', {
    className: _style['default'].btn, // <-- Note: After passing through _interopRequireDefault, this need to access default here.
  });
}

css

Generator options for css modules.

js
export default {
  module: {
    generator: {
      css: {
        // options
      },
    },
  },
};

css.exportsOnly

Same as module.generator["css/auto"].exportsOnly.

js
export default {
  module: {
    generator: {
      css: {
        exportsOnly: false,
      },
    },
  },
};

css.esModule

Same as module.generator["css/auto"].esModule.

js
export default {
  module: {
    generator: {
      css: {
        esModule: true,
      },
    },
  },
};

["css/global"]

Generator options for css/global modules.

js
export default {
  module: {
    generator: {
      'css/global': {
        // options
      },
    },
  },
};

["css/global"].exportsConvention

Same as module.generator["css/auto"].exportsConvention.

js
export default {
  module: {
    generator: {
      'css/global': {
        exportsConvention: 'camel-case',
      },
    },
  },
};

["css/global"].exportsOnly

Same as module.generator["css/auto"].exportsOnly.

js
export default {
  module: {
    generator: {
      'css/global': {
        exportsOnly: false,
      },
    },
  },
};

["css/global"].localIdentName

Same as module.generator["css/auto"].localIdentName.

js
export default {
  module: {
    generator: {
      'css/global': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};

["css/global"].localIdentHashDigest

Same as module.generator["css/auto"].localIdentHashDigest.

js
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};

["css/global"].localIdentHashDigestLength

Same as module.generator["css/auto"].localIdentHashDigestLength.

js
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};

["css/global"].localIdentHashFunction

Same as module.generator["css/auto"].localIdentHashFunction.

js
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};

["css/global"].localIdentHashSalt

Same as module.generator["css/auto"].localIdentHashSalt.

js
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};

["css/global"].esModule

Same as module.generator["css/auto"].esModule.

js
export default {
  module: {
    generator: {
      'css/global': {
        esModule: true,
      },
    },
  },
};

["css/module"]

Generator options for css/module modules.

js
export default {
  module: {
    generator: {
      'css/module': {
        // options
      },
    },
  },
};

["css/module"].exportsConvention

Same as module.generator["css/auto"].exportsConvention.

js
export default {
  module: {
    generator: {
      'css/module': {
        exportsConvention: 'camel-case',
      },
    },
  },
};

["css/module"].exportsOnly

Same as module.generator["css/auto"].exportsOnly.

js
export default {
  module: {
    generator: {
      'css/module': {
        exportsOnly: false,
      },
    },
  },
};

["css/module"].localIdentName

Same as module.generator["css/auto"].localIdentName.

js
export default {
  module: {
    generator: {
      'css/module': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};

["css/module"].localIdentHashDigest

Same as module.generator["css/auto"].localIdentHashDigest.

js
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};

["css/module"].localIdentHashDigestLength

Same as module.generator["css/auto"].localIdentHashDigestLength.

js
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};

["css/module"].localIdentHashFunction

Same as module.generator["css/auto"].localIdentHashFunction.

js
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};

["css/module"].localIdentHashSalt

Same as module.generator["css/auto"].localIdentHashSalt.

js
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};

["css/module"].esModule

Same as module.generator["css/auto"].esModule.

js
export default {
  module: {
    generator: {
      'css/module': {
        esModule: true,
      },
    },
  },
};

json.JSONParse

  • Type: boolean
  • Default: true

Use JSON.parse when the JSON string is longer than 20 characters.

js
export default {
  module: {
    generator: {
      json: {
        JSONParse: false,
      },
    },
  },
};