Quick Start#

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

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.

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:  http://192.168.0.1:8081

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: