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.

Installation#

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

npm add @rspack/core -D

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

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
});

function rspack(
  options: MultiRspackOptions | RspackOptions,
  callback?: Callback<Error, MultiStats | Stats>,
): null | MultiCompiler | Compiler;

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.

See Compiler API for more details.

Run#

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.

import { rspack } from '@rspack/core';

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

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

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

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.

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.

See Compiler.watch for more details.

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.

See Stats API for more details.

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');
  },
);

See MultiCompiler API for more details.

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 handles all conditions:

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#

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 => {
    // ...
  });
});

sources object#

@rspack/core exports the webpack-sources module through sources. It provides a set of classes for creating and manipulating source code fragments and source maps. When developing Rspack plugins, you can use these classes to handle and manipulate source code.

import { sources } from '@rspack/core';

const { RawSource } = sources;
const source = new RawSource('console.log("Hello, world!");');

For detailed usage, please refer to the webpack-sources documentation.