#Experiments

Enables experimental features.

• Type: object

#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.outputModule

• Type: boolean
• Default: false

When enabled, Rspack outputs ECMAScript module syntax whenever possible. For example, import() to load chunks, ESM exports to expose chunk data, and more.

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

#experiments.css

• Type: boolean
• Default: false

When enabled, Rspack enables native CSS support and CSS-related parser and generator options.

• module.parser["css/auto"]
• module.parser.css
• module.parser["css/module"]
• module.generator["css/auto"]
• module.generator.css
• module.generator["css/module"]

#Migration

To use CSS in Rspack 2.0, you need to manually add CSS rules to your configuration:

export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        type: 'css/auto',
      },
    ],
  },
};

#Legacy usage (deprecated)

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

#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.incremental

This option has been moved to top-level incremental.

#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.

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.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.

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.

#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 #233.

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.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. Currently, only import defer * as ns from "./module" is supported, while import.defer() will be supported in future versions.

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