Quick start#

Get up to speed quickly with a new Rspack based project.

Creating project using scaffolding#

Using the Rspack CLI#

You can scaffold a simple project setup using the Rspack CLI directly. Invoke the following command:

npm create rspack@latest

Then follow the input prompts in your terminal.

Community Toolchain#

There are already a few Rspack-based toolchains in the community:

• If you're looking for a React framework to build a web application, you can try Modern.js Framework.
• If you want to build a static site, you can try Rspress.
• If you want a fast and production-ready setup that works in a standalone and monorepo environment and comes with built-in tooling, you can try Nx.

Modern.js#

Modern.js Framework is a Rspack-based progressive React framework that provides a complete solution for building web applications. It supports nested routes, server-side rendering, and provides out-of-the-box CSS solutions such as styled components and Tailwind CSS.

Learn more about Modern.js in the official documentation.

Rspress#

Rspress is a static site generator based on Rspack. It provides a complete solution for building static sites and includes the following features:

• 🚀 Fast Startup: Based on Rust-based build tool and markdown/mdx compiler, the build speed is extremely fast, bringing you the ultimate development experience.
• 📚 MDX Support: MDX is a powerful way to write content, allowing you to use React components in Markdown.
• 📦 Built-in Full Text Search: Automatically generates a full-text search index for you during building process, providing out-of-the-box full-text search capabilities.
• 🌈 Static Site Generation: In production, it automatically builds into static HTML files, which can be easily deployed anywhere.
• 🔌 Providing Plugin System: Providing a plugin system, you can customize the build process and theme according to your needs.

Learn more about Rspress in the official documentation.

Using Nx#

The fastest way to get up to speed quickly and leverage Rspack and React in a production-ready setting is to use the dedicated Rspack Nx plugin. This gives you a pre-configured setup, integrating Rspack with React, TypeScript, ESLint, Jest, and Cypress for e2e testing.

Run the following command to set up a new Nx workspace with React and Rspack:

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

The pre-configured setup is already ready to work with Rspack, TypeScript, TSX and React. In addition it also comes with Jest and Cypress for testing and ESLint for linting.

Once created you can simply npm start (or pnpm start or yarn start) to start the development server. You can also run npm run build (or pnpm run build or yarn run build) to build the application for production and similarly run npm run test (or pnpm run test or yarn run test) to run the unit tests.

You can learn more about Nx at https://nx.dev.

Manual installation#

Installation#

We'll start by creating a project directory, generating an NPM package.json, and then installing @rspack/cli locally:

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

Creating your first bundle#

Adding some source files#

First create an entry file src/index.js and helper file src/answer.js

import { answer } from './answer';
function render() {
  document.getElementById(
    'root'
  ).innerHTML = `The answer to the universe is ${answer}.`;
}
render();

export const answer = 42;

Adding the configuration file#

Rspack configures the bundle behavior by default via rspack.config.js whose structure is nearly identical to webpack.config.js. Put the rspack.config.js file in your project's root directory, for example:

const path = require('path');

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

A simple way to invoke the build is npx rspack build. You could also customize the config file name with npx rspack build -c <your-config-file>. The console output will look something like this:

npx rspack build
Time: 21.388ms

At this point we have generated main.js and main.js.map files in the dist directory.

Let's create a index.html manually in the dist folder by copying the following content to verify the correctness of the output.

<!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>

Open dist/index.html in a web browser, and confirm that The answer to the universe is 42. is rendered successfully on the page.

Adding a third-party library#

Rspack can package not only local dependencies, but also third-party dependencies. Let's refactor our application to use the React renderer. First, add react as a package.json dependency:

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

Rename src/index.js to src/index.jsx. Then refactor the code to use React:

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 has built-in support for React, so you don't need any special configuration. But don't forget to change the entry in rspack.config.js to src/index.jsx:

const path = require('path');

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

Add HTML support#

Rspack has built-in support for HTML, so you don't need to manually configure the path of the JavaScript bundle for the HTML file. You can use the HTML functionality like this:

module.exports = {
  entry: {
    main: './src/index.jsx',
  },
  builtins: {
    html: [{ template: './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>

Now invoke npx rspack build. Confirm that dist/index.html was generated with the correct JavaScript path inserted automatically:

<!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>Hello Rspack!</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="/main.js" defer></script>
  </body>
</html>

Hot Module Replacement (HMR)#

Rspack has built-in support for HMR. If you're using React, this includes built-in support for fast-refresh, so you don't need to configure it.

To experience HMR, invoke npx rspack serve. Next, make a change to the src/answer.js source file:

export const answer = 'Rspack';

You should observe that the web browser automatically updates to show The answer to the universe is Rspack.