Compiler#

Compiler Methods#

run#

Start a compilation, and callbacked when the compilation is completed or aborted due to an error.

run(callback:  (
  error: Error, // Only including compiler-related errors, such as configuration errors, not including compilation errors
  stats: Stats, // detailed information generated during the compilation
) => void): void;

compiler.run((err, stats) => {
  // Deal with the compiler errors
  handlerCompilerError(err);
  // Deal with the compilation errors
  handlerModuleErrors(stats.toJson().errors);
  // Deal with the result
  handleBuildResult(stats);
  // End this compilation
  compiler.close(closeErr => {
    // Start a new compilation
    compiler.run((err, stats) => {});
  });
});

watch#

Watching files and directories, start a compilation process after they change, and callbacked every time the compilation is completed or aborted due to an error.

watch(
  watchOptions: WatchOptions, // options for starting the watching
  handler: (error: Error, stats: Stats) => void // callback when every compilation ends
): Watching; // watching controller

const watching = compiler.watch(
  {
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // Deal with the result
    handleBuildResult(stats);
  },
);

The Watching object provides the following methods:

• watch:
  • Type: (files: string[], dirs: string[], missing: string[]): void
  • Usage: Add the files and directories that need to be watched.
• invalidate:
  • Type: (callback: () => void): void
  • Usage: Immediately end this round of watching and start a compilation with the currently recorded file changes, without stopping the watcher.
• suspend:
  • Type: (): void
  • Usage: Enter the state of only watching and will not start a new compilation.
• resume:
  • Type: (): void
  • Usage: Exit the state of only watching and start a compilation with the currently recorded file changes.
• close:
  • Type: (callback: () => void): void
  • Usage: Stop the watcher.

compile#

Create a compilation and run it, which is the basic method that compiler.run and compiler.watch depend on.

compile(
  callback: (compilation: Compilation) => void // callback after this compilation
): void

close#

Close the current compiler, and handle low-priority tasks such as caching during this period.

close(
  callback: (err: Error) => void // callback after closing
): void;

getInfrastructureLogger#

Create a logger object that is not associated with any compilation, which is used to print global logs.

getInfrastructureLogger(name: string): Logger;

getCache#

Create a cache object to share data in the build process.

getCache(name: string): CacheFacade;

purgeInputFileSystem#

Stop the read loop of the input file system, which internally contains a timer and may cause the process to still not be able to exit after calling compiler.close.

purgeInputFileSystem(): void;

createChildCompiler#

Allows running another instance of Rspack inside of Rspack. However, as a child with different settings and configurations applied. It copies all hooks and plugins from the parent (or top-level compiler) and creates a child Compiler instance. Returns the created Compiler.

createChildCompiler(
  compilation: Compilation,
  compilerName: string,
  compilerIndex: number,
  outputOptions: OutputOptions,
  plugins: RspackPlugin[]
): Compiler;

runAsChild#

Running the child compiler, which will doing a complete compiling and generate the assets.

runAsChild(
  callback(
    err: Error, // error related to the child compiler
    entries: Chunk[], // chunks generated by the child compiler
    compilation: Compilation, // the compilation created by the child compiler
  ): void;
): void;

isChild#

Whether this compiler is a child compiler.

isChild(): boolean;

Compiler Properties#

hooks#

See compiler hooks for more details.

rspack#

• Type: typeof rspack

Get the exports of @rspack/core to obtain the associated internal objects. This is especially useful when you cannot directly reference @rspack/core or there are multiple Rspack instances.

A common example is accessing the sources object in a Rspack plugin:

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

webpack#

• Type: typeof rspack

Equivalent to compiler.rspack, this property is used for compatibility with webpack plugins.

If the Rspack plugin you are developing needs to be webpack compatible, you can use this property instead of compiler.rspack.

console.log(compiler.webpack === compiler.rspack); // true

name#

• Type: string

Get the name:

• For the root compiler, it is equivalent to name.
• For the child compiler, it is the value passed into createChildCompiler.
• For the MultiCompiler and in the KV form, it is the key.

context#

Current project root directory:

• Created through new Compiler, it is the value passed in.
• Created through rspack({}), it is context configuration.

root#

• Type: Compiler

Get the root of the child compiler tree.

options#

• Type: RspackOptionsNormalized

Get the full options used by this compiler.

watchMode#

• Type: boolean

Whether started through compiler.watch.

watching#

• Type: Watching

Get the watching object, see watch method for more details.

running#

• Type: boolean

Whether the compilation is currently being executed.

inputFileSystem#

• Type: InputFileSystem

Get the proxy object used for reading from the file system, which has optimizations such as caching inside to reduce duplicate reading of the same file.

outputFileSystem#

• Type: OutputFileSystem

Get the proxy object used for writing to the file system, fs by default.

watchFileSystem#

• Type: WatchFileSystem

Get the proxy object used for watching files or directories changes, which provides a watch method to start watching, and passes in the changed and removed items in the callback.

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.

const rspack = require('@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');
  },
);

It can also be created through new MultiCompiler:

const compiler1 = new Compiler({
  /* */
});
const compiler2 = new Compiler({
  /* */
});

new MultiCompiler([compiler1, compiler2]);

new MultiCompiler([compiler1, compiler2], {
  parallelism: 1, // the maximum number of parallel compilers
});

new MultiCompiler({
  name1: compiler1,
  name2: compiler2,
});

MultiCompiler also provides some methods and attributes of the Compiler.

MultiCompiler Methods#

setDependencies#

Specify the dependency relationship between the compilers, using compiler.name as the identifier, to ensure the execution order of the compilers.

setDependencies(compiler: Compiler, dependencies: string[]): void;

validateDependencies#

Check whether the dependency relationship between the compilers is legal. If there is a cycle or a missing dependency, it will trigger the callback.

validateDependencies(
  callback: (err: Error) => void; // callback when there is an error
): boolean

run#

Execute the run method of each compiler according to the dependency relationship to start the compilation process.

run(callback: (err: Error, stats: MultiStats) => void): void;

watch#

Execute the watch method of each compiler according to the dependency relationship to start watching, and start a compilation process after the file changes.

watch(
  watchOptions: WatchOptions,
  handler: (err: Error, stats: MultiStats) => void,
): MultiWatching

close#

Execute the close method of each compiler to close them, and handle low-priority tasks such as caching during this period.

close(callback: (err: Error) => void): void;

purgeInputFileSystem#

Execute the purgeInputFileSystem of each compiler to stop the read loop of the file system

purgeInputFileSystem(): void;

getInfrastructureLogger#

Create a logger object that is not associated with any compilation, which is used to print global logs.

getInfrastructureLogger(name: string): Logger;

Same with compilers[0].getInfrastructureLogger()

MultiCompiler Properties#

compilers#

• Type: Compiler[]

Get all included compilers.

options#

• Type: RspackOptionsNormalized[]

Get all the full options used by the compilers.

inputFileSystem#

• Type: InputFileSystem

Set the proxy object used for reading from the file system for each compiler.

outputFileSystem#

• Type: OutputFileSystem

Set the proxy object used for writing from the file system for each compiler.

watchFileSystem#

• Type: WatchFileSystem

Set the proxy object used for watching files or directories changes for each compiler.

running#

• Type: boolean

Whether the compilation is currently being executed.