CC 4.0 License

The content of this section is derived from the content of the following links and is subject to the CC BY 4.0 license.

The following contents can be assumed to be the result of modifications and deletions based on the original contents if not specifically stated.

JavaScript API

Rspack provides a set of JavaScript APIs to be used in JavaScript runtimes like Node.js or Bun.

The JavaScript API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the stats configuration options will not have any effect in the rspack() call.

TIP

@rspack/core is designed based on Webpack's JavaScript API to ensure functional consistency and a similar user experience.

Installation

To start using the Rspack JavaScript API, first install @rspack/core if you haven’t yet:

npm install --save-dev @rspack/core

Then require the @rspack/core module in your JavaScript file:

build.js
import rspack from '@rspack/core';

rspack()

The imported rspack function is fed a Rspack Configuration Object and runs the Rspack compiler if a callback function is provided:

import rspack from '@rspack/core';

rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Done processing
});
TIP

The err object will not include compilation errors. Those must be handled separately using stats.hasErrors(), which will be covered in detail in the Error Handling section of this guide. The err object will only contain rspack-related issues, such as misconfiguration, etc.

TIP

You can provide the rspack function with an array of configurations. See the MultiCompiler section below for more information.

Compiler Instance

If you don’t pass the rspack runner function a callback, it will return a Rspack Compiler instance. This instance can be used to manually trigger the Rspack runner or have it build and watch for changes, much like the CLI. The Compiler instance provides the following methods:

  • .run(callback)
  • .watch(watchOptions, handler)

Typically, only one master Compiler instance is created, although child compilers can be created in order to delegate specific tasks. The Compiler is ultimately a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading, bundling, and writing work to registered plugins.

The hooks property on a Compiler instance is used to register a plugin to any hook event in the Compiler's lifecycle. The RspackOptionsApply utilities are used by Rspack to configure its Compiler instance with all the built-in plugins.

The run method is then used to kickstart all compilation work. Upon completion, the given callback function is executed. The final logging of stats and errors should be done in this callback function.

WARNING

The API only supports a single concurrent compilation at a time. When using run or watch, call close and wait for it to finish before calling run or watch again. Concurrent compilations will corrupt the output files.

Run

Calling the run method on the Compiler instance is much like the quick run method mentioned above:

import rspack from '@rspack/core';

const compiler = rspack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close(closeErr => {
    // ...
  });
});
WARNING

Don't forget to close the compiler, so that low-priority work (like persistent caching) have the opportunity to complete.

Watching

Calling the watch method triggers the rspack runner, but then watches for changes (much like CLI: rspack --watch), as soon as Rspack detects a change, runs again. Returns an instance of Watching.

watch(watchOptions, callback);
import rspack from '@rspack/core';

const compiler = rspack({
  // ...
});

const watching = compiler.watch(
  {
    // Example
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // Print watch/build result here...
    console.log(stats);
  },
);

Watching options are covered in detail here.

WARNING

Filesystem inaccuracies may trigger multiple builds for a single change. In the example above, the console.log statement may fire multiple times for a single modification. Users should expect this behavior and may check stats.hash to see if the file hash has actually changed.

Close Watching

The watch method returns a Watching instance that exposes .close(callback) method. Calling this method will end watching:

watching.close(closeErr => {
  console.log('Watching Ended.');
});
WARNING

It’s not allowed to watch or run again before the existing watcher has been closed or invalidated.

Invalidate Watching

Using watching.invalidate, you can manually invalidate the current compiling round, without stopping the watch process:

watching.invalidate();

Stats Object

The stats object that is passed as a second argument of the rspack() callback, is a good source of information about the code compilation process. It includes:

  • Errors and Warnings (if any)
  • Timings
  • Module and Chunk information

The Rspack CLI uses this information to display nicely formatted output in your console.

TIP

When using the MultiCompiler, a MultiStats instance is returned that fulfills the same interface as stats, i.e. the methods described below.

This stats object exposes the following methods:

stats.hasErrors()

Can be used to check if there were errors while compiling. Returns true or false.

stats.hasWarnings()

Can be used to check if there were warnings while compiling. Returns true or false.

stats.toJson(options)

Returns compilation information as a JSON object. options can be either a string (a preset) or an object for more granular control:

stats.toJson('minimal');
stats.toJson({
  assets: false,
  hash: true,
});

All available options and presets are described in the stats documentation.

stats.toString(options)

Returns a formatted string of the compilation information (similar to CLI output).

Options are the same as stats.toJson(options) with one addition:

stats.toString({
  // Add console colors
  colors: true,
});

Here’s an example of stats.toString() usage:

import rspack from '@rspack/core';

rspack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(
      stats.toString({
        chunks: false, // Makes the build much quieter
        colors: true, // Shows colors in the console
      }),
    );
  },
);

MultiCompiler

The MultiCompiler module allows Rspack to run multiple configurations in separate compilers. If the options parameter in the Rspack's JavaScript API is an array of options, Rspack applies separate compilers and calls the callback after all compilers have been executed.

import rspack from '@rspack/core';

rspack(
  [
    { entry: './index1.js', output: { filename: 'bundle1.js' } },
    { entry: './index2.js', output: { filename: 'bundle2.js' } },
  ],
  (err, stats) => {
    process.stdout.write(stats.toString() + '\n');
  },
);
WARNING

Multiple configurations will not be run in parallel. Each configuration is only processed after the previous one has finished processing.

Error Handling

For good error handling, you need to account for these three types of errors:

  • Fatal rspack errors (wrong configuration, etc)
  • Compilation errors (missing modules, syntax errors, etc)
  • Compilation warnings

Here’s an example that does all that:

import rspack from '@rspack/core';

rspack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err.stack || err);
      if (err.details) {
        console.error(err.details);
      }
      return;
    }

    const info = stats.toJson();

    if (stats.hasErrors()) {
      console.error(info.errors);
    }

    if (stats.hasWarnings()) {
      console.warn(info.warnings);
    }

    // Log result...
  },
);

Custom File Systems

Differences with webpack
  1. The current support for inputFileSystem in Rspack is limited, and the ability to customize the filesystem read capability consistent with webpack has not yet been implemented. Please refer to: Issue #5091.

  2. With Rspack, when using a specified output file system, there's no longer a requirement to supply mkdirp and join utility methods.

By default, Rspack reads files and writes files to disk using a normal file system. However, it is possible to change the input or output behavior using a different kind of file system (memory, webDAV, etc). To accomplish this, one can change the inputFileSystem or outputFileSystem. For example, you can replace the default outputFileSystem with memfs to write files to memory instead of to disk:

import { createFsFromVolume, Volume } from 'memfs';
import rspack from '@rspack/core';

const fs = createFsFromVolume(new Volume());
const compiler = rspack({
  /* options */
});

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // Read the output later:
  const content = fs.readFileSync('...');
  compiler.close(closeErr => {
    // ...
  });
});