ContextQMD
Back to Rspack

Module methods

website/docs/en/api/runtime-api/module-methods.mdx

2.0.116.9 KB
Original Source

import WebpackLicense from '@components/WebpackLicense'; import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/api/module-methods/" />

Module methods

This section covers all methods available in code compiled with Rspack. When using Rspack to bundle your application, you can pick from a variety of module syntax styles including ES modules and CommonJS.

While Rspack supports multiple module syntaxes, we recommend following a single syntax for consistency and to avoid odd behaviors or bugs.

Actually Rspack would enforce the recommendation for .mjs files, .cjs files or .js files when their nearest parent package.json file contains a "type" field with a value of either "module" or "commonjs". Please pay attention to these enforcements before you read on:

  • .mjs or .js with "type": "module" in package.json
    • No CommonJS allowed, for example, you can't use require, module.exports or exports
    • File extensions are required when importing, e.g, you should use import './src/App.mjs' instead of import './src/App' (you can disable this enforcement with rules[].resolve.fullySpecified)
  • .cjs or .js with "type": "commonjs" in package.json
    • Neither import nor export is available

ES modules (recommended)

Rspack support ES modules syntax natively, you can use static import, export and import() syntax.

:::warning Keep in mind that you will still probably need SWC or Babel for other ES6+ features. :::

import

Statically import the export of another module.

js
import MyModule from './my-module.js';
import { NamedExport } from './other-module.js';

You can also import Data URI, this allow you to embed Base64 encoded JavaScript code directly in the import statement:

js
// Equivalent to import a module that contains `console.log('hello')`
import 'data:text/javascript;charset=utf-8;base64,Y29uc29sZS5sb2coJ2hlbGxvJyk=';

// Equivalent to import a module that contains `export const number = 42;`
import { number } from 'data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOw==';

export

Export anything as a default or named export.

js
// Named exports
export var Count = 5;
export function Multiply(a, b) {
  return a * b;
}

// Default export
export default {
  // Some data...
};

Dynamic import()

ts
function import(path: string): Promise;

Dynamically load modules, see Dynamic import for more details.

Calls to import() are treated as split points, meaning the requested module and its children are split out into a separate chunk.

js
if (module.hot) {
  import('lodash').then((_) => {
    // Do something with lodash (a.k.a '_')...
  });
}

:::warning This feature relies on Promise internally. If you use import() with legacy browsers, remember to shim Promise using a polyfill such as core-js, es6-promise or promise-polyfill. :::

Dynamic expressions in import()

It is not possible to use a fully dynamic import statement, such as import(foo). Because foo could potentially be any path to any file in your system or project.

The import() must contain at least some information about where the module is located. Bundling can be limited to a specific directory or set of files so that when you are using a dynamic expression, every module that could potentially be requested on an import() call is included.

For example, import(./locale/${language}.json) will cause every .json file in the ./locale directory to be bundled into the new chunk. At run time, when the variable language has been computed, any file like english.json or german.json will be available for consumption.

js
// imagine we had a method to get language from cookies or other storage
const language = detectVisitorLanguage();
import(`./locale/${language}.json`).then((module) => {
  // do something with the translations
});

Magic comments

<ApiMeta specific={['Rspack', 'Webpack']} />

Inline comments to make features work. By adding comments to the import, we can do things such as specify chunk name or select different loading modes. For a full list of these magic comments see the code below followed by an explanation of what these comments do.

js
// Single target
import(
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackExports: ["default", "named"] */
  /* webpackFetchPriority: "high" */
  'module'
);

// Multiple possible targets
import(
  /* webpackInclude: /\.json$/ */
  /* webpackExclude: /\.noimport\.json$/ */
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackPrefetch: true */
  /* webpackPreload: true */
  `./locale/${language}`
);
webpackIgnore
  • Type: boolean

When set to true, Rspack will skip analysis and bundling processing for the dynamic import. This results in:

  1. The module's dependencies will not be analyzed during build time
  2. The module will not be bundled into a separate chunk file
  3. The import operation will be executed by the browser's native import() at runtime

This is particularly useful for dynamically loading ESM third-party libraries from external CDNs, for example:

js
import('https://esm.sh/react' /* webpackIgnore: true */).then((React) => {
  console.log(React.version); // 19.0.0
});

webpackIgnore also applies to the new URL() syntax. By default, Rspack will parse module identifiers in new URL() and bundle the referenced module into the build output. When you need Rspack to skip processing a particular new URL(), you can add the webpackIgnore: true comment:

js
// Rspack will process this URL and bundle './index.css' into the build output
const url1 = new URL('./index.css', import.meta.url);

// Rspack will ignore this URL and preserve the original module identifier
const url2 = new URL(/* webpackIgnore: true */ './index.css', import.meta.url);
webpackMode
  • Type: "eager" | "lazy" | "weak" | "lazy-once"
  • Default: 'lazy'

Different modes for resolving dynamic imports can be specified. The following options are supported:

  • 'lazy' (default): Generates a lazy-loadable chunk for each import()ed module.
  • 'lazy-once': Generates a single lazy-loadable chunk that can satisfy all calls to import(). The chunk will be fetched on the first call to import(), and subsequent calls to import() will use the same network response. Note that this only makes sense in the case of a partially dynamic statement, e.g. import("./locales/${language}.json"), where multiple module paths that can potentially be requested.
  • 'eager': Generates no extra chunk. All modules are included in the current chunk and no additional network requests are made. A Promise is still returned but is already resolved. In contrast to a static import, the module isn't executed until the call to import() is made.
  • 'weak': Tries to load the module if the module function has already been loaded in some other way (e.g. another chunk imported it or a script containing the module was loaded). A Promise is still returned, but only successfully resolves if the chunks are already on the client. If the module is not available, the Promise is rejected. A network request will never be performed. This is useful for universal rendering when required chunks are always manually served in initial requests (embedded within the page), but not in cases where app navigation will trigger an import not initially served.
webpackPrefetch
  • Type:
    • number: chunk prefetch priority
    • boolean: false means not to prefetch, true means priority is 0

Tells the browser that the resource is probably needed for some navigation in the future, see Prefetching/Preloading modules for more details.

webpackPreload
  • Type:
    • number: chunk preload priority
    • boolean: false means not to preload, true means priority is 0

Tells the browser that the resource might be needed during the current navigation, , see Prefetching/Preloading modules for more details.

webpackChunkName
  • Type:: string

A name for the new chunk.

webpackFetchPriority
<ApiMeta addedVersion="1.0.0" />
  • Type:: "low" | "high" | "auto"

Set fetchPriority for specific dynamic imports. It's also possible to set a global default value for all dynamic imports by using the module.parser.javascript.dynamicImportFetchPriority option.

webpackInclude
<ApiMeta addedVersion="1.0.0" />
  • Type:: Regexp

A regular expression that will be matched against during import resolution. Only modules that match will be bundled.

webpackExclude
<ApiMeta addedVersion="1.0.0" />
  • Type:: Regexp

A regular expression that will be matched against during import resolution. Any module that matches will not be bundled.

:::info Note that webpackInclude and webpackExclude options do not interfere with the prefix. eg: ./locale. :::

webpackExports
<ApiMeta addedVersion="1.0.0" />
  • Type:: string | string[]

Tells webpack to only bundle the specified exports of a dynamically import()ed module. It can decrease the output size of a chunk.

CommonJS

Rspack is also support CommonJS syntax natively, you can use require and module.exports methods.

require

Synchronously retrieve the exports from another module.

js
require(dependency: string);

require.resolve

Synchronously retrieves the module ID without executing the module code. This method will include the module in the final bundle. The returned module ID is primarily intended for use with require.cache[id] or the Rspack internal __webpack_require__(id) function. Direct use of this method should be avoided in most application scenarios.

js
require.resolve(dependency: string);

:::warning Module ID's type can be a number or a string depending on the optimization.moduleIds configuration. :::

require.cache

Multiple requires of the same module result in only one module execution and only one export. Therefore a cache in the runtime exists. Removing values from this cache causes new module execution and a new export.

js
var d1 = require('dependency');
require('dependency') === d1;
delete require.cache[require.resolve('dependency')];
require('dependency') !== d1;

require.context

<ApiMeta specific={['Rspack', 'Webpack']} />

require.context is a function specific to webpack that allows you to dynamically require a set of modules.

You can use require.context in your code, and Rspack will parse and reference the matching modules during the build process.

:::tip The return value of require.context is the same as import.meta.webpackContext. We recommend using import.meta.webpackContext, which is more powerful. :::

  • Type:
ts
function requireContext(
  /**
   * A directory to search.
   */
  directory: string,
  /**
   * Whether subdirectories should be searched.
   * @default true
   */
  includeSubdirs?: boolean,
  /**
   * A regular expression to match files.
   * @default /^\.\/.*$/ (any file)
   */
  filter?: RegExp,
  /**
   * Module loading mode.
   * @default 'sync'
   */
  mode?: 'sync' | 'eager' | 'weak' | 'lazy' | 'lazy-once',
): Context;
  • Example:
js
// Create a context, with files from the test directory that
// can be required with a module specifier ending with `.test.js`.
const context = require.context('./test', false, /\.test\.js$/);
js
// Create a context with all files in the parent folder and
// descending folders ending with `.stories.js`.
const context = require.context('../', true, /\.stories\.js$/);
js
// If mode is set to 'lazy', the underlying modules will be loaded asynchronously
const context = require.context('./locales', true, /\.json$/, 'lazy');

:::tip Rspack uses static analysis to parse the parameters of require.context during compilation. Therefore, the parameters must be literals.

For example, the value of filter cannot be a variable, nor can it be the value generated by new RegExp(). It can only be a regular expression literal. :::

require.ensure

<ApiMeta specific={['Rspack', 'Webpack']} />

:::tip We recommend using the more standard import() instead of require.ensure(). :::

Split the given dependencies into a separate bundle and load them asynchronously.

  • Type:
ts
function requireEnsure(
  /**
   * List of modules that need to be loaded asynchronously
   */
  dependencies: String[],
  /**
   * Called once all modules in dependencies have been loaded.
   * You can still use require() inside this function to load modules.
   */
  callback: function(),
  /**
   * A function that is executed when Rspack fails to load the dependencies.
   */
  errorCallback?: function(error),
  /**
   * A name given to the chunk created by this particular require.ensure().
   * By passing the same chunkName to various require.ensure() calls,
   * we can combine their code into a single chunk, resulting in only one bundle that the browser must load.
   */
  chunkName?: string
): Context;

:::warning

  • This feature relies on Promise internally. If you use require.ensure in older browsers, remember to shim Promise using a polyfill such as es6-promise or promise-polyfill.
  • As in webpack, the callback can also accept a parameter named require (and it must be named require). This parameter behaves the same as the CommonJS global require, but we recommend using the global require directly instead, because loaders may rename the callback parameter and break dependency analysis.

:::

  • Example:
ts
var a = require('normal-dep');

if (module.hot) {
  require.ensure(['b'], function () {
    var c = require('c');

    // Do something special...
  });
}

require.resolveWeak

<ApiMeta specific={['Rspack', 'Webpack']} />

Similar to require.resolve, but this method won't pull the module into the final bundle. It's what is considered a "weak" dependency.

js
require.resolveWeak(dependency: string);

For example:

js
if (__webpack_modules__[require.resolveWeak('module')]) {
  // Do something when module is available...
}
if (require.cache[require.resolveWeak('module')]) {
  // Do something when module was loaded before...
}

// You can perform dynamic resolves ("context")
// similarly to other require/import methods.
const page = 'Foo';
__webpack_modules__[require.resolveWeak(`./page/${page}`)];

Data URI module

Rspack supports importing Data URI modules using the import and require syntax.

  • import
js
import DataURI from 'data:text/javascript,export default 42';
  • require
js
require('data:text/javascript,module.exports = 42');

In addition, Base64 encoded requests are also supported:

js
const {
  number,
  fn,
} = require('data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOwpleHBvcnQgZnVuY3Rpb24gZm4oKSB7CiAgcmV0dXJuICJIZWxsbyB3b3JsZCI7Cn0=');

::: tip The Data URI module can be used as a method to implement virtual modules, such as combining with a Loader to dynamically load custom modules at runtime. :::

Built-in rules

Rspack supports these MIME types for data URI modules by default: application/json, text/javascript, application/javascript, application/node, and application/wasm. This means that when you create data URI modules with these MIME types, Rspack will automatically recognize them.

Rspack's built-in MIME rules are as follows:

js
const defaultMimeRules = [
  {
    mimetype: 'application/node',
    type: 'javascript/auto',
  },
  {
    mimetype: 'application/json',
    type: 'json',
  },
  {
    mimetype: {
      or: ['text/javascript', 'application/javascript'],
    },
    type: 'javascript/esm',
    // ...
  },
  {
    mimetype: 'application/wasm',
    type: 'webassembly/async',
    // ...
  },
];

Custom rules

You can also use rules[].mimetype to extend the matching rules for Data URI modules, for example, to add custom loaders for text/javascript:

js
export default {
  module: {
    rules: [
      {
        mimetype: 'text/javascript',
        use: [
          // ...
        ],
      },
    ],
  },
};