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

Experiments

Enables experimental features.

• Type: object

:::tip In minor releases, Rspack may change the APIs of experimental features. If you're using experimental features, pay attention to the minor release notes for detailed explanations of changes. :::

experiments.asyncWebAssembly

• Type: boolean
• Default: true

Supports the new WebAssembly according to the updated specification, making WebAssembly modules async.

export default {
  experiments: {
    asyncWebAssembly: true,
  },
};

experiments.buildHttp

• Type: HttpUriOptions
• Default: undefined

type HttpUriOptions = {
  /**
   * A list of allowed URIs
   */
  allowedUris: (string | RegExp)[];
  /**
   * Define the location to store the lockfile
   */
  lockfileLocation?: string;
  /**
   * Define the location for caching remote resources
   */
  cacheLocation?: string | false;
  /**
   * Detect changes to remote resources and upgrade them automatically
   * @default false
   */
  upgrade?: boolean;
  /**
   * Custom http client
   */
  httpClient?: (
    url: string,
    headers: Record<string, string>,
  ) => Promise<{
    status: number;
    headers: Record<string, string>;
    body: Buffer;
  }>;
};

After enabling this feature, Rspack can build remote resources that start with the http(s): protocol. Rspack will download the resources to the local machine and then bundle them.

By default, Rspack will generate rspack.lock and rspack.lock.data in the context folder as the locations of the Lockfile and the cache respectively. You can also configure them through lockfileLocation and cacheLocation.

:::note You should commit the files at lockfileLocation and cacheLocation to the version control system so that no network requests will be made during the production build. :::

For example:

export default {
  experiments: {
    buildHttp: {
      allowedUris: ['https://'],
      lockfileLocation: path.join(__dirname, 'my_project.lock'),
      cacheLocation: path.join(__dirname, 'my_project.lock.data'),
    },
  },
};

With this feature enabled, you can import modules directly from URLs:

// Import from a remote URL
import { something } from 'https://example.com/module.js';

// Or import assets
import imageUrl from 'https://example.com/image.png';

experiments.deferImport

• Type: boolean
• Default: false

When enabled, Rspack will support bundling the Deferred Imports Evaluation proposal, which allows deferring the evaluation of a module until its first use. Rspack supports both import defer * as ns from "./module" and import.defer() syntax.

export default {
  experiments: {
    deferImport: true,
  },
};

:::info Known Limitation Currently, when using output.module: true, defer import syntax for external modules will be compiled to standard import syntax.

For example, if jquery is configured as external:

import defer * as $ from 'jquery';

It will generate:

import * as __rspack_external_jquery from 'jquery';

This is because defer import syntax is not yet supported by any runtime. In the future, Rspack will support preserving defer import syntax based on the target configuration, generating the following code:

import defer * as __rspack_external_jquery from 'jquery';

:::

experiments.futureDefaults

• Type: boolean
• Default: false

Uses defaults from the next major Rspack version and shows warnings for any problematic configuration.

export default {
  experiments: {
    futureDefaults: true,
  },
};

experiments.nativeWatcher

• Type: boolean
• Default: false

By default, Rspack uses Watchpack to monitor file changes, which generally works well in most scenarios. However, in certain specific environments, issues may arise. For example, Watchpack may experience performance problems when there are a large number of file changes. More detail see: Watchpack issue #223.

If you encounter performance issues with the default watcher, you can try enabling nativeWatcher.

After enabling nativeWatcher, Rspack will use the Rust Native file system to monitor file changes, enabling incremental file change detection, which provides better performance and stability.

export default {
  watchOptions: {
    // Other watch options...
  },
  experiments: {
    nativeWatcher: true,
  },
};

experiments.pureFunctions

• Type: boolean
• Default: false

Enables cross-module side-effect-free function call optimization, including the /*#__NO_SIDE_EFFECTS__*/ annotation and module.parser.javascript.pureFunctions. Functions marked through annotations or user configuration are omitted from the output when they are not actually used.

For more background, see pureFunctions and NO_SIDE_EFFECTS annotation.

Use this option to turn on the capability itself. To manually mark identifiers in matched modules — exported functions in a third-party module, or imports/locals in your own files — configure module.parser.javascript.pureFunctions through module.rules[i].parser so the rule only applies to the intended modules.

export default {
  experiments: {
    pureFunctions: true,
  },
  module: {
    rules: [
      {
        test: /node_modules\/some-library\/index\.js$/,
        parser: {
          pureFunctions: ['isString'],
        },
      },
    ],
  },
};

:::warning This option depends on optimization.sideEffects. If you disable optimization.sideEffects, pure-function hints will not be analyzed. :::

experiments.useInputFileSystem

• Type: false | RegExp[]
• Default: false

By default, Rspack reads files from disk using a native file system. However, it is possible to change the file system using a different kind of file system. To accomplish this, one can change the inputFileSystem. For example, you can replace the default inputFileSystem with memfs to virtual Modules.

But due to the overheads calling file system implemented in Node.js side, it will slow down Rspack a lot. So we make a trade off by providing the useInputFileSystem config, to tell rspack to read file from the native file system or from modified inputFileSystem.

In below example, you can simply replace the default input file system to any file system satisfied the InputFileSystem interface.

:::info Note The replacing of compiler.inputFileSystem will only take effect before compiler.run called; Replacing after compiler.run will not take effect. :::

More detailed case can be found here

export default {
  entry: {
    index: './virtual_index.js',
  },
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.beforeCompile.tap('SimpleInputFileSystem', () => {
          compiler.inputFileSystem = {
            readFile(path, cb) {
              cb(null, `// the file content`);
            },
            stat(p, cb) {
              cb(null, fsState);
            },
          };
        });
      },
    },
  ],
  experiments: {
    useInputFileSystem: [/virtual_.*\.js/],
  },
};

Work with webpack-virtual-modules

import VirtualModulesPlugin from 'webpack-virtual-modules';

var virtualModules = new VirtualModulesPlugin({
  'virtual_entry.js': `
    require("./src/another_virtual.js");
    require("./src/disk_file.js")
    `,
  'src/another_virtual.js': 'module.exports = 42',
});

export default {
  entry: './virtual_entry.js',
  plugins: [virtualModules],
  experiments: {
    useInputFileSystem: [/.*virtual.*\.js$/],
  },
};

When access to virtual_entry.js and src/another_virtual.js which match the regular expressions of experiments.useInputFileSystem, Rspack will use the input file system wrapped by VirtualModulesPlugin; other than that, src/disk_file.js will be accessed by the native file system.