快速上手#

通过本章节来了解如何快速上手并使用 Rspack。

• 创建新项目：使用 CLI 创建一个全新的 Rspack 或 Rsbuild 项目。
• 从现有项目迁移：从一个基于 webpack 的项目迁移到 Rspack。

生态#

作为一个底层打包工具，Rspack 拥有丰富的技术生态，包含多种框架、工具和解决方案。这些生态项目涵盖了从框架到开发工具的各个方面，能够满足不同场景下的开发需求，提供开箱即用的体验。

查看 生态 页面来探索这些生态项目。

环境准备#

Rspack 支持使用 Node.js、Deno 或 Bun 作为运行时。

Node.js#

对于 Node.js，请安装 Node.js >= 16 版本，推荐使用 Node.js LTS 版本。

通过以下命令检查当前使用的 Node.js 版本：

node -v

如果你的环境中尚未安装 Node.js，或是版本过低，可以通过 nvm 或 fnm 安装。

下面是通过 nvm 安装的例子：

# 安装 Node.js LTS
nvm install --lts
# 切换到 Node.js LTS
nvm use --lts

创建新项目#

使用 Rsbuild#

Rsbuild 是由 Rspack 驱动的高性能构建工具，由 Rspack 团队开发。它默认包含了一套精心设计的构建配置，提供开箱即用的开发体验，并能够充分发挥出 Rspack 的性能优势。

我们推荐使用 Rsbuild 来创建新项目，执行如下命令即可：

npm create rsbuild@latest

更多信息参考 Rsbuild - 快速上手。

使用 Rspack CLI#

Rspack CLI 是对标 webpack CLI 的工具，提供基础的 serve 和 build 构建命令。

Rsbuild 支持 Node.js >= 16，但是 Rspack CLI 要求 Node.js 版本 >= 18.12.0

执行如下命令即可创建基于 Rspack CLI 的项目：

npm create rspack@latest

然后按照提示操作。

快速创建#

create-rspack 和 create-rsbuild 提供了一些 CLI 选项。通过设置这些 CLI 选项，你可以跳过交互式的选择步骤，一键创建项目。

比如，一键创建 React 项目到 my-project 目录：

# Rspack CLI
npx create-rspack --dir my-project --template react
# Rsbuild
npx create-rsbuild --dir my-project --template react
# 使用缩写
npx create-rsbuild -d my-project -t react

在线示例#

我们提供了基于 Rsbuild 的在线示例，通过示例项目，你可以直观感受 Rspack 的构建性能和 Rsbuild 的开发体验：

• Rsbuild CodeSandbox 示例

手动安装#

首先创建一个项目目录，并生成一个 npm package.json 文件：

mkdir rspack-demo
cd rspack-demo
npm init -y

然后安装 @rspack/core 和 @rspack/cli 为 dev 依赖：

npm add @rspack/core @rspack/cli -D

更新构建脚本以使用 Rspack CLI：

{
  "scripts": {
    "dev": "rspack dev",
    "build": "rspack build"
  }
}

接下来，查看 配置 Rspack 来了解如何配置 Rspack。

从现有项目迁移#

如果你需要从一个现有项目迁移迁移到 Rspack 技术栈，可以参考以下指南：

• 从 webpack 迁移到 Rspack
• 从 webpack 迁移到 Rsbuild
• 从 Create React App 迁移到 Rsbuild
• 从 Vue CLI 迁移到 Rsbuild
• 从 Vite 迁移到 Rsbuild
• 从 Tsup 迁移到 Rslib
• 从 Storybook 迁移

安装 canary 版本#

当你需要测试或验证 Rspack 未发布至稳定版的功能时，可能需要使用 canary 版本。

Rspack canary 版本的 scope 会带有 -canary 后缀。例如 @rspack/core 的 canary 包名为 @rspack-canary/core。要使用这些版本，你可以配置包管理器（npm/yarn/pnpm/bun）的 overrides。

以下是使用 pnpm overrides 的示例：

{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-canary/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}

此外，Rspack 社区提供了 install-rspack 工具来方便地安装 canary 版本：

npx install-rspack --version latest # 安装当前的 latest 版本
npx install-rspack --version canary # 安装当前的 canary 版本
npx install-rspack --version 1.0.0-canary-d614005-20250101082730 # 安装指定的 canary 版本