Quick Start


Modern.js Builder has been rebranded as Rsbuild. This document will no longer be updated.

  • If you are using the Modern.js framework, please visit the Modern.js framework documentation directly.
  • If you are using the CLI or Node API of Modern.js Builder, you can easily migrate to Rsbuild, please visit the Rsbuild repository for more information.

Environment preparation

Before getting started, you will need to install Node.js, and ensure that your Node.js version is higher than 16.2.0. We recommend using the LTS version of Node.js 18.

You can check the currently used Node.js version with the following command:

node -v

If you do not have Node.js installed in your current environment, or the installed version is lower than 16.2.0, you can use nvm or fnm to install the required version.

Here is an example of how to install the Node.js 18 LTS version via nvm:

# Install the long-term support version of Node.js 18
nvm install 18 --lts

# Make the newly installed Node.js 18 as the default version
nvm alias default 18

# Switch to the newly installed Node.js 18
nvm use 18
nvm and fnm

Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm is more mature and stable, while fnm is implemented using Rust, which provides better performance than nvm.

Use the Modern.js Framework

The Modern.js Framework uses Modern.js Builder as its build tool by default. If you are a business developer, you do not need to manually install Builder, just create a Modern.js project and use all the features provided by Builder.

npx @modern-js/create@latest my-app

Please refer to Modern.js - Introduction and Modern.js - Quick Start to learn how to use Modern.js framework.

About the documentation

Modern.js framework documentation and Modern.js Builder documentation are deployed under two separate sites. If you encounter any build-related problems while using the Modern.js framework, you can always refer to the documentation of Modern.js Builder to find solutions.

Use the Builder CLI Tool

Modern.js Builder provides a lightweight CLI tool that includes basic commands such as dev and build. It is primarily used for building non-React projects.

If your project is not based on React, for example, if you are developing a Vue project, you can use the Builder CLI tool to build your project.

Please refer to Use Builder CLI for more information on how to use it.

Use Builder in a Front-end Framework

If you are developing a front-end framework, you can use Builder by following these steps:

1. Install Builder

You need to install two packages:

  • @modern-js/builder: This is the core package of Builder, which exports the core API of Builder.
  • @modern-js/builder-rspack-provider: To provide the building capabilities based on Rspack.
npm add @modern-js/builder @modern-js/builder-rspack-provider -D

if you want to use webpack instead of Rspack, you can replace the @modern-js/builder-rspack-provider with @modern-js/builder-webpack-provider:

When performing a version upgrade, please ensure that the Builder and Provider packages you install are of the same version.

2. Create Builder Instance

There are two steps to creating a Builder instance:

First you need to initialize the Builder Provider and pass in the builderConfig config object. Builder provides a lot of configs that allow you to customize the build behavior. At this point, you don't need to know the specific content of the config, just pass in an empty object. You can find all available configs in API - config.

  • Initialize the Rspack Provider:
import { createBuilder } from '@modern-js/builder';
import { builderWebpackProvider } from '@modern-js/builder-webpack-provider';

const provider = builderWebpackProvider({
  builderConfig: {
    // some configs
  • Initialize the Rspack Provider:
import { createBuilder } from '@modern-js/builder';
import { builderRspackProvider } from '@modern-js/builder-rspack-provider';

const provider = builderRspackProvider({
  builderConfig: {
    // some configs

After getting the provider instance, you can call the createBuilder method to create a Builder instance object:

const builder = await createBuilder(provider, {
  entry: {
    index: './src/index.ts',

Except the entry option, the createBuilder method also provides some other options, which you can learn more about in API - createBuilder.

3. Call Builder Instance Method

The Builder instance provides some methods, which you can use according to the usage scenarios.

To start local development, it is recommended to use the builder.startDevServer method, which will start a local Dev Server.

await builder.startDevServer();

After successfully starting Dev Server, you can see the following logs:

info    Starting dev server...

  > Local:    http://localhost:8081
  > Network:

To deploy the App to production environment, it is recommended to use the builder.build method, which will build the production outputs.

await builder.build();

For more introduction of Builder instance methods, please read the Builder Instance chapter.

After completing the above three steps, you have learned the basic usage of Builder. Next, you can customize the build process through the Builder plugin and Builder configs.

Next Step

You may want: