指南
配置
API
博客
指南
配置
API
博客
简体中文

快速上手

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

使用脚手架快速创建

使用 Rspack CLI

你可以直接使用 Rspack CLI 来创建一个基础项目，调用以下命令即可：

npm create rspack@latest

然后按照提示操作即可。

社区工具链

社区中已经有一些基于 Rspack 的工具链：

  • 如果你需要一个 React 框架来构建 Web 应用，你可以尝试 Modern.js Framework。
  • 如果你需要开发一个静态站点(如文档站)，你可以尝试 Rspress.
  • 如果你需要在 Monorepo 项目中使用 Rspack，并使用快速、可扩展的构建系统，你可以尝试 Nx。

Modern.js

Modern.js 是字节跳动 Web 工程体系的开源版本，它提供了一个基于 Rspack 实现的渐进式 React 框架，并为开发 Web 应用提供了完整的解决方案。框架支持嵌套路由、服务器端渲染（SSR），并提供开箱即用的 CSS 解决方案，比如 styled-components 和 Tailwind CSS。

请阅读 官方文档 来了解更多关于 Modern.js 的信息。

Rspress

Rspress 是一个基于 Rspack 的静态站点生成器，它包含如下的特性：

  • 🚀 快速构建：基于 Rust 构建工具和 Markdown/MDX 编译器，构建速度极快，为你带来更舒适的开发体验。
  • 📚 MDX 支持：MDX 是一种强大的内容编写方式，允许你在 Markdown 中使用 React 组件。
  • 📦 内置全文搜索：在构建过程中自动生成全文搜索索引，提供开箱即用的全文搜索能力。
  • 🌈 静态站点生成：在生产环境中，它会自动构建成静态 HTML 文件，可以轻松部署到任何地方。
  • 🔌 提供插件系统：提供一个插件系统，你可以根据自己的需要定制构建过程和自定义主题。

你可以去 官网 了解更多关于 Rspress 的信息。

使用 Nx

Nx 是一个快速、可扩展的构建系统，Rspack 团队与 Nx 团队合作提供了 Rspack Nx 插件。该插件会给你一个预设项目，将 Rspack 与 React、TypeScript、ESLint、Jest 和用于 e2e 测试的 Cypress 整合在一起，使你能迅速搭建一个用于生产环境的应用。

运行以下命令，用 React 和 Rspack 建立一个新的 Nx workspace。

npx create-nx-workspace myrspackapp --preset=@nx/rspack

这个预设项目已经包含了 Rspack、TypeScript、TSX 和 React。此外，它还配备了用于测试的 Jest 和 Cypress 、用于代码规范校验的 ESLint。

创建成功后，你可以直接用 npm start 来启动开发服务器。你也可以运行 npm run build 来为生产环境构建应用程序、运行 npm run test 来运行单元测试。

你可以在 https://nx.dev 了解更多关于 Nx 的信息。

手动安装指南

安装

首先我们创建一个目录，初始化 npm ，然后在本地安装 @rspack/cli，通过如下方式进行安装:

mkdir rspack-demo
cd rspack-demo
npm init -y
npm install -D @rspack/cli

创建第一个 bundle

项目创建

首先创建一个入口文件 src/index.js 和 一个 src/answer.js

src/index.js
import { answer } from './answer';
function render() {
  document.getElementById(
    'root'
  ).innerHTML = `the answer to the universe is ${answer}`;
}
render();
src/answer.js
export const answer = 42;

使用配置文件

Rspack 默认通过 rspack.config.js 来配置打包行为，我们可以在项目根目录下创建一个 rspack.config.js 文件，然后在里面配置打包行为，如下:

rspack.config.js
const path = require('path');

module.exports = {
  entry: {
    main: './src/index.js',
  },
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist'),
  },
};

我们通过 npx rspack build 执行构建，你也可以通过 npx rspack build -c <your-config-file> 来自定义配置文件名。build 的输出结果如下：

npx rspack build
Time: 21.388ms
INFO

@rspack/cli 默认的 stats 只输出 errors、warnings 和 timings 的信息，可以通过 stats 设置输出更多构建信息。

此时我们在 dist 目录里生成了 main.js 和 main.js.map 两个文件， 我们在 dist 里创建如下的 dist/index.html 来验证生成的产物运行是否正常。

dist/index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>hello rspack</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="./main.js"></script>
  </body>
</html>

在浏览器里打开 dist/index.html，我们发现浏览器里正常渲染了 the answer to the universe is 42。

添加三方依赖

Rspack 不仅可以打包本地依赖，也可以打包三方依赖，我们现在用 React 来重构我们的应用，首先添加 react 作为依赖：

npm install --save react@18 react-dom@18

将 src/index.js 重命名为 src/index.jsx 并使用 React 重构代码：

src/index.jsx
import { answer } from './answer';
import React from 'react';
import ReactDOM from 'react-dom/client';
const App = () => {
  return <div>the answer to the universe is {answer}</div>;
};
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

Rspack 内置了对 React 的支持，你无需任何配置，但是别忘了将 rspack.config.js 里的入口改为 src/index.jsx。

rspack.config.js
const path = require('path');

module.exports = {
  entry: {
    main: './src/index.jsx',
  },
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist'),
  },
};

添加 html 支持

Rspack 内置了对 html 的支持，无需自己手动的在 html 里配置产物 js 的地址，通过如下方式使用 html 功能：

rspack.config.js
module.exports = {
  entry: {
    main: './src/index.jsx',
  },
  builtins: {
    html: [{ template: './src/index.html' }],
  },
};
src/index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>hello rspack</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

此时我们执行 npx rspack build，我们发现 dist/index.html 里自动带上了 js 的地址：

dist/index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="/main.js" defer></script>
  </body>
</html>

体验 HMR

Rspack 内置了对 HMR 的支持，并对 React 项目内置了 fast-refresh 的支持，你无需配置，通过 npx rspack serve 即可体验 React 的 HMR， 我们修改 src/answer.js

src/answer.js
export const answer = 'Rspack';

我们发现浏览器上的内容自动更新为 the answer to the universe is Rspack。