JavaScript API

Rspack 提供了一组 JavaScript API，可在 Node.js、Deno、Bun 等 JavaScript 运行时中使用。

当你需要自定义构建或开发流程时，JavaScript API 非常有用，因为此时所有的报告和错误处理都必须自行实现，Rspack 仅仅负责编译的部分。所以 stats 配置项不会在 rspack() 调用中生效。


           @rspack/core

是对齐 webpack 的 JavaScript API 设计的，旨在提供一致的功能和相似的使用体验。

开始使用 Rspack 的 JavaScript API 之前，首先你需要安装 @rspack/core ：

npm

yarn

pnpm

bun

npm add @rspack/core -D

在 JavaScript 文件中，引入 @rspack/core 模块：

ESM

CJS

build.mjs

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

rspack()

导入的 rspack 函数会将 配置对象 传给 Rspack，如果同时传入回调函数会在 Rspack compiler 运行时被执行：

import { rspack } from '@rspack/core';
rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  // 处理完成
function rspack(
  options: MultiRspackOptions | RspackOptions,
  callback?: Callback<Error, MultiStats | Stats>,
): null | MultiCompiler | Compiler;

err 对象不包含编译错误，必须使用 stats.hasErrors() 单独处理，文档的错误处理将对这部分进行详细介绍。err 对象只包含 Rspack 相关的问题，例如配置错误等。


          你也可以为 rspack() 函数提供一个配置数组。更多详细信息，请查看
          
           MultiCompiler
          
          章节。


        
         
          #
         
         Compiler 实例
        
        
         如果你不向
         
          rspack
         
         传入可执行的回调函数，它会返回一个 Rspack
         
          Compiler
         
         实例。你可以通过手动执行它或者为它的构建时添加一个监听器，就像
         
          CLI
         
         类似。Compiler 实例提供了以下方法：
        
        
         
          .run(callback)
         
        
        
         
          .watch(watchOptions, handler)
         
        
        
         通常情况下，仅会创建一个主要
         
          Compiler
         
         实例，虽然可以创建一些子 compiler 来代理到特定任务。
         
          Compiler
         
         基本上只是执行最低限度的功能，以维持生命周期运行的功能。它将所有的加载、打包和写入工作，都委托到注册过的插件上。
        
        
         
          Compiler
         
         实例上的
         
          hooks
         
         属性，用于将一个插件注册到
         
          Compiler
         
         的生命周期中的所有钩子事件上。Rspack 使用
         
          
           RspackOptionsApply
          
         
         来配置
         
          Compiler
         
         实例以及所有内置插件。
        
        
         关于 Compiler 的更多细节请参考
         
          Compiler API
         
         。
        
        
         
          
           
            
             
            
           
           
            Compiler.ts
           
          
         
        
        
         
          #
         
         compiler.run
        
        
         使用
         
          run
         
         方法启动所有编译工作。完成之后，执行传入的的
         
          callback
         
         函数。最终记录下来的概括信息（stats）和错误（errors），都应在这个 callback 函数中获取。
        
        
         
          
           import { rspack } from '@rspack/core';
const compiler = rspack({
  // ...
compiler.run((err, stats) => {
  // ...
  compiler




    
.close(closeErr => {
    // ...
该 API 不支持并发编译。当你使用 run 或 watch 时，请先调用 close 并等待其完成，然后再调用 run 或 watch。并发编译会破坏输出文件。
          
         
         
          
           
            #
           
           compiler.watch
          
          
           调用
           
            watch
           
           方法会触发 Rspack 执行，但之后会监听变更（很像 CLI 命令：
           
            rspack --watch
           
           ），一旦 Rspack 检测到文件变更，就会重新执行编译。该方法返回一个
           
            Watching
           
           实例。
          
          
           
            
             import { rspack } from '@rspack/core';
const compiler = rspack({
  // ...
const watching = compiler.watch(
    // 示例
    aggregateTimeout: 300,
    poll: undefined,
  (err, stats) => {
    // 这里打印 watch/build 结果...
    console.log(stats);
Watching 配置选项的细节可以在这里查询。
文件系统不正确的问题，可能会对单次修改触发多次构建。因此，在上面的示例中，一次修改可能会多次触发 console.log 语句。用户应该预知此行为，并且可能需要检查 stats.hash 来查看文件哈希是否确实变更。
            
           
           
            
             关于 Watching 的更多细节请参考
             
              
               Compiler.watch
              
             
             。
            
            
             
              
               
                
                 
                
               
               
                Watching.ts
               
              
             
            
            
             
              #
             
             Stats
            
            
             
              stats
             
             对象会被作为
             
              
               rspack()
              
             
             回调函数的第二个参数传递，可以通过它获取到代码编译过程中的有用信息，包括：
            
            
             错误和警告（如果有的话）
            
            
             模块和 chunk 信息
            
            
             
              Rspack CLI
             
             正是基于这些信息在控制台展示友好的格式输出。
            
            当使用
            
             MultiCompiler
            
            时，会返回一个
            
             MultiStats
            
            实例，它实现与
            
             stats
            
            相同的接口，也就是下面描述的方法。
            
            
           
          
         
        
        
         
          
           关于 Stats 对象更多细节请参考
           
            Stats API
           
           。
          
          
           
            
             
              
               
              
             
             
              Stats.ts
             
            
           
          
          
           
            #
           
           MultiCompiler
          
          
           
            MultiCompiler
           
           模块可以让 Rspack 同时执行多个配置。如果传给 Rspack 的 JavaScript API 的
           
            options
           
           参数，该参数由是由多个配置对象构成的数组，Rspack 会相应地创建多个 compiler 实例，并且在所有 compiler 执行完毕后调用
           
            callback
           
           方法。
          
          
           
            
             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');
关于 MultiCompiler 对象更多细节请参考 MultiCompiler API。
#错误处理
完备的错误处理中需要考虑以下三种类型的错误:
致命的 Rspack 错误（配置出错等）
编译错误（缺失的模块，语法错误等）
下面是一个覆盖这些场景的示例:
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...
#自定义文件系统
与 webpack 的差异

当前 Rspack 对于 inputFileSystem 的支持存在限制，尚未实现与 webpack 一致的自定义文件系统读取能力。请参考：Issue #5091。
Rspack 在指定的输出文件系统，不再需要提供 mkdirp 和 join 工具方法。
默认情况下，Rspack 使用普通文件系统来读取文件并将文件写入磁盘。但是，还可以使用不同类型的文件系统（内存, webDAV 等）来更改输入或输出行为。为了实现这一点，可以改变 inputFileSystem 或 outputFileSystem。例如，可以使用 memfs 替换默认的 outputFileSystem，以将文件写入到内存中，而不是写入到磁盘：
import { createFsFromVolume, Volume } from 'memfs';
import { rspack } from '@rspack/core';
const fs = createFsFromVolume(new Volume());
const compiler = rspack({
  /* 配置选项 */
compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // 之后读取输出：
  const content = fs.readFileSync('...');
  compiler.close(closeErr => {
    // ...
#sources 对象
@rspack/core 通过 sources 导出了 webpack-sources 模块。它提供了一组 class，用于创建和操作源代码片段和源码映射。在开发 Rspack 插件时，你可以使用这些 class 来处理和操作源代码。
import { sources } from '@rspack/core';

# JavaScript API

# rspack()

# Compiler 实例

# compiler.run

# compiler.watch

# Stats

# MultiCompiler

#错误处理

#自定义文件系统

#sources 对象

JavaScript API

rspack()

Compiler 实例

compiler.run

compiler.watch

Stats

MultiCompiler

错误处理

自定义文件系统

`sources` 对象