Quick Start

Environment preparation

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

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

node -v
# v16.19.1

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

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

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

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

# Switch to the newly installed Node.js 16
nvm use 16

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 engine 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 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 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 is the core package of Builder and exports the core API.
  • @modern-js/builder-webpack-provider is a provider for Builder, providing webpack-based building capabilities.
pnpm add @modern-js/builder @modern-js/builder-webpack-provider -D

When upgrading the version, please make sure that Builder and Provider you are installing are 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.

import { createBuilder } from '@modern-js/builder';
import { builderWebpackProvider } from '@modern-js/builder-webpack-provider';

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

After getting the provider object, 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 it 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...
info    Dev server running at:

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