Quick Start#

Environment#

Node.js#

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

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 18.20.8, you can use nvm or fnm to install the required version.

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

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

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

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

Additionally, after installing nvm or fnm, when there is a .nvmrc file containing lts/jod in the repository's root directory, the system will automatically install or switch to the correct Node.js version upon entering the repository.

pnpm#

It is recommended to use pnpm to manage dependencies:

npm install -g pnpm@9

Installation#

Modern.js provides the @modern-js/create tool to create projects. It does not require global installation and can be run on-demand using npx.

You can create a project in an existing empty directory:

mkdir myapp && cd myapp
npx @modern-js/create@latest

You can also create a project directly in a new directory:

npx @modern-js/create@latest myapp

Initialize#

@modern-js/create provides an interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:

? Please select the programming language: TS
? Please select the package manager: pnpm

After create the project, Modern.js will automatically install dependencies and create a git repository.

[INFO] dependencies are automatically installed
[INFO] git repository has been automatically created
[INFO] Success！
You can run the following command in the directory of the new project:
pnpm run dev          # Starting dev server
pnpm run build        # Build the app for production
pnpm run serve        # Preview the production build locally
pnpm run lint         # Run ESLint and automatically fix problems
pnpm run new          # Enable optional features or add a new entry

Now, the project structure is as follows:

Development#

Run pnpm run dev in the project to start the project:

$ pnpm run dev
> modern dev

  Modern.js Framework

ready   Client compiled in 0.86 s

  > Local:    http://localhost:8080/
  > Network:  http://192.168.0.1:8080/

Open http://localhost:8000/ in your browser to see the page content.

Configuration#

In a Modern.js project created using @modern-js/create, a modern.config.ts file is generated by default.

You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:

import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  runtime: {
    router: true,
  },
  server: {
    ssr: true,
  },
  plugins: [appTools({
      bundler: 'rspack', // Set to 'webpack' to enable webpack
  }),],
});

After running pnpm run dev again, you can find that the project has completed page rendering on the server in the browser's Network menu.

Core npm Package#

In a newly created project, the @modern-js/app-tools npm package is installed by default. It is the core package of the Modern.js framework and provides the following capabilities:

• It offers commonly used CLI commands such as modern dev, modern build, and more.
• It integrates Modern.js Core, providing capabilities for configuration parsing, plugin loading, and more.
• It integrates Rsbuild, providing build capabilities.
• It integrates Modern.js Server, providing capabilities for development and production servers.

@modern-js/app-tools is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register appTools in the plugins field of the configuration file:

import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  plugins: [appTools()],
});

Build the project#

To build the production artifacts of the project, run pnpm run build in the project:

$ pnpm run build

> modern build

  Modern.js Framework

info    Starting production build...
info    Type checker is enabled. It may take some time.
ready   Client compiled in 6.19 s
info    Production file sizes:

  File                                       Size        Gzipped
  dist/routes-manifest.json                  0.74 kB     0.28 kB
  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
  dist/html/main/index.html                  6.0 kB      2.6 kB
  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB

  Total size:  531.8 kB
  Gzipped size:  176.7 kB

By default, the build artifacts are generated in dist/, with the following directory structure:

If you need to customize the directory of the build artifacts, please refer to Output files.

Verify#

Run pnpm run serve in the project to verify whether the build artifacts run normally locally:

$ pnpm run serve

> modern serve

  Modern.js Framework

info    Starting production server...

  > Local:    http://localhost:8080/
  > Network:  http://192.168.0.1:8080/

Open http://localhost:8000/ in the browser, and the content should be consistent with that of pnpm run dev.

Deployment#

After local develop, you can refer to the Deployment section to deploy the project to the server.