import Columns from '@components/Columns'; import { Collapse, CollapsePanel } from '@components/Collapse'; import CompilationType from '../../types/compilation.mdx'; import { Badge } from '@theme';

Stats

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 Stats object provides two important methods:

• toJson(): Output information in the form of a Stats JSON object, which is often used in analysis tools.
• toString(): Output information in the form of a string, which is often used in the CLI tools.

Rspack also provides StatsFactory and StatsPrinter to fine-grained control the output object or string.

Compilation ===============> Stats JSON =================> Stats Output
           ╰─ StatsFactory ─╯           ╰─ StatsPrinter ─╯
╰─────────── stats.toJson() ───────────╯
╰───────────────────────── stats.toString() ──────────────────────────╯

Create a stats object related to a compilation through compilation.getStats() or new Stats(compilation).

:::warning Timing matters

stats.toJson() and stats.toString() rely on compilation artifacts that are finalized in compiler.hooks.done. If they are called at other times (for example, on stale Stats objects captured earlier), some stats fields can be incomplete.

For complete and stable stats output, call these methods in compiler.hooks.done:

compiler.hooks.done.tap('MyPlugin', (stats) => {
  const statsJson = stats.toJson({ all: false, errors: true, warnings: true });
  const statsText = stats.toString({ preset: 'errors-warnings' });
  console.log(statsJson.errors);
  console.log(statsText);
});

:::

Stats methods

hasErrors

Can be used to check if there were errors while compiling.

Type:

hasErrors(): boolean;

Use the return value to handle compilation errors:

if (stats.hasErrors()) {
  console.error('Compilation failed');
}

hasWarnings

Can be used to check if there were warnings while compiling.

Type:

hasWarnings(): boolean;

Use the return value to handle compilation warnings:

if (stats.hasWarnings()) {
  console.warn('Compilation completed with warnings');
}

toJson

Return the compilation information in the form of a Stats JSON object. The Stats configuration can be a string (preset value) or an object for granular control:

Type:

toJson(options?: StatsValue): StatsCompilation;

Use the 'minimal' preset and print the number of errors:

const statsJson = stats.toJson('minimal');
console.log(statsJson.errorsCount);

Use an options object to select the fields to include, then print the compilation hash:

const statsJson = stats.toJson({
  assets: false,
  hash: true,
});
console.log(statsJson.hash);

toString

Return the compilation information in the form of a formatted string (similar to the output of CLI).

Type:

toString(opts?: StatsValue): string;

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

Stats properties

compilation

Type: Compilation

Get the related compilation object.

hash

Type: string | null

Get the hash of this compilation, same as Compilation.hash.

When using it as a string, check for null first:

if (stats.hash !== null) {
  console.log(stats.hash);
}

MultiStats

When using MultiCompiler to run multiple compilation tasks, their results are packaged as a MultiStats object. It provides a combined hash and methods for checking, serializing, and formatting all child compilation results.

hash

Type: string

Get the hash formed by concatenating the hashes of all child compilations.

Print the concatenated hash:

console.log(multiStats.hash);

hasErrors

Returns true if any child compilation has errors.

Type:

hasErrors(): boolean;

Use the return value to handle errors across all child compilations:

if (multiStats.hasErrors()) {
  console.error('At least one compilation failed');
}

hasWarnings

Returns true if any child compilation has warnings.

Type:

hasWarnings(): boolean;

Use the return value to handle warnings across all child compilations:

if (multiStats.hasWarnings()) {
  console.warn('At least one compilation completed with warnings');
}

toJson

Returns a StatsCompilation whose children array contains the Stats JSON for each child compilation. Fields enabled for every child, such as errors and warnings, are also aggregated at the top level.

Type:

toJson(options: boolean | StatsPresets | MultiStatsOptions): StatsCompilation;

Use one preset for every child compilation and inspect the number of results:

const statsJson = multiStats.toJson('minimal');
console.log(statsJson.children?.length);

MultiStatsOptions also supports a children option for configuring each child compilation individually. The following example prints the errors from the first child compilation:

const statsJson = multiStats.toJson({
  children: [
    { all: false, errors: true },
    { all: false, assets: true },
  ],
});
console.log(statsJson.children?.[0]?.errors);

toString

Format each child compilation according to the stats configuration, then concatenate the results into one string.

Type:

toString(options: boolean | StatsPresets | MultiStatsOptions): string;

Use one preset for every child compilation and print the combined output:

const statsText = multiStats.toString('minimal');
console.log(statsText);

Stats factory

Used to generate the stats json object from the Compilation, and provides hooks for fine-grained control during the generation process.

It can be got through compilation.hooks.statsFactory. Or create a new one by new StatsFactory().

Hooks

See StatsFactory hooks for more details.

create

The core method of StatsFactory, according to the type to specify the current data structure, find and run the corresponding generator to generate the stats json item.

stats = statsFactory.create('compilation', compilation, {});

The StatsFactory object only handles the calling of hooks, and the processing code of the corresponding type can be found in DefaultStatsFactoryPlugin.

Stats printer

Used to generate the output string from the stats json object, and provides hooks for fine-grained control during the generation process.

It can be got through compilation.hooks.statsPrinter. Or create a new one by new StatsPrinter().

Hooks

See StatsPrinter hooks for more details.

print

The core method of StatsPrinter, according to the type to specify the current data structure, find and run the corresponding generator to generate the output string of the stats item.

stats = statsPrinter.print('compilation', stats, {});

The StatsPrinter object only handles the calling of hooks, and the processing code of the corresponding type can be found in DefaultStatsPrinterPlugin.