Quick Start

Environment

Node.js

Before getting started, you will need to install Node.js, and ensure that your Node.js version is not lower than v20.19.5. 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 v20.19.5, 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

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.

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@10

Note

Modern.js also supports dependency management with yarn and npm.

Installation

Initialize

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

@modern-js/create will directly create the application without providing an interactive Q & A interface:

🚀 Welcome to Modern.js

📦 Creating project "myapp"...

✨ Project created successfully! 🎉

📋 Next, you can run the following commands:

📁 Enter the project directory:

  cd myapp

🔧 Initialize Git repository:

  git init

📥 Install project dependencies:

  pnpm install

⚡ Start the development server:

  pnpm start

Now, the project structure is as follows:

.
├── biome.json
├── modern.config.ts
├── package.json
├── README.md
├── src
│   ├── modern-app-env.d.ts
│   ├── modern.runtime.ts
│   └── routes
│       ├── index.css
│       ├── layout.tsx
│       └── page.tsx
└── tsconfig.json

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

modern.config.ts

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

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

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

modern.config.ts

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

dist
├── html
│   └── index
├── modern.config.json
├── route.json
├── routes-manifest.json
└── static
    ├── css
    └── js

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.js Framework

info    Starting production server...

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

Open http://localhost:8080/ 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.

#Quick Start

#Environment

#Node.js

#pnpm

#Installation

#Initialize

#Development

#Configuration

#Core npm Package

#Build the project

#Verify

#Deployment