快速上手
环境准备
Node.js
在开始使用前，你需要安装 Node.js，并保证 Node.js 版本不低于 18.20.8，我们推荐使用 Node.js 22 的 LTS 版本。
你可以通过以下命令检查当前使用的 Node.js 版本：
node -v如果你当前的环境中尚未安装 Node.js，或是安装的版本低于 18，可以通过 nvm 或 fnm 安装需要的版本。
下面是通过 nvm 安装 Node.js 22 LTS 版本的例子：
# 安装 Node.js 22 的长期支持版本
nvm install 22 --lts
# 将刚安装的 Node.js 22 设置为默认版本
nvm alias default 22
# 切换到刚安装的 Node.js 22
nvm use 22nvm 和 fnm 都是 Node.js 版本管理工具。相对来说，nvm 较为成熟和稳定，而 fnm 是使用 Rust 实现的，比 nvm 提供了更好的性能。
此外，在安装 nvm 或 fnm 后，然后只要仓库根目录下有内容为 lts/jod 的 .nvmrc 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
Modern.js 目前仍支持 Node 16，但会在 2025 年 6 月正式终止对 Node.js 16 的支持，为确保您的项目顺利过渡，请在 2025 年 6 月前完成 Node.js 版本升级。
pnpm
推荐使用 pnpm 来管理依赖：
npm install -g pnpm@9
Modern.js 同样支持使用 yarn、npm 进行依赖管理。
安装
Modern.js 提供了 @modern-js/create 工具来创建项目，不需要全局安装，直接使用 npx 按需运行即可。
你可以在已有的空目录来创建项目：
mkdir myapp && cd myapp
npx @modern-js/create@latest也可以直接用新目录创建项目：
npx @modern-js/create@latest myapp初始化项目
@modern-js/create 会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
? 请选择开发语言 TS
? 请选择包管理工具 pnpm在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
[INFO] 依赖自动安装成功
[INFO] git 仓库初始化成功
[INFO] 创建成功！
可在新项目的目录下运行以下命令：
pnpm run dev # 启动开发服务器
pnpm run build # 构建生产环境产物
pnpm run serve # 启动生产环境服务
pnpm run lint # 运行 ESLint 并自动修复问题
pnpm run new # 启用可选功能或创建项目要素现在，项目结构如下：
.
├── node_modules
├── src
│ ├── modern-app-env.d.ts
│ └── routes
│ ├── index.css
│ ├── layout.tsx
│ └── page.tsx
├── modern.config.ts
├── package.json
├── pnpm-lock.yaml
├── README.md
└── tsconfig.json启动项目
在项目中执行 pnpm run dev 即可启动项目：
$ 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/在浏览器中打开 http://localhost:8000/，可以看到页面内容。
使用配置
通过 @modern-js/create 创建的 Modern.js 项目中，会默认生成 modern.config.ts 文件。
你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
import { appTools, defineConfig } from '@modern-js/app-tools';
export default defineConfig({
server: {
ssr: true,
},
plugins: [appTools()],
});重新执行 pnpm run dev，在浏览器 Network 菜单中，可以发现项目已经在服务端完成了页面渲染。
核心 npm 包
在新创建的工程中，默认会安装 @modern-js/app-tools npm 包，它是 Modern.js 框架的核心包，主要提供以下能力：
- 提供
modern dev,modern build等常用的 CLI 命令。 - 集成 Modern.js Core，提供配置解析、插件加载等能力。
- 集成 Rsbuild，提供构建能力。
- 集成 Modern.js Server，提供开发和生产服务器相关能力。
@modern-js/app-tools 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 plugins 字段中注册 appTools：
import { appTools, defineConfig } from '@modern-js/app-tools';
export default defineConfig({
plugins: [appTools()],
});构建项目
在项目中执行 pnpm run build 即可构建项目生产环境产物：
$ 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构建产物默认生成到 dist/，目录结构如下：
dist
├── html
│ └── main
├── modern.config.json
├── route.json
├── routes-manifest.json
└── static
├── css
└── js如果你需要自定义构建产物的目录，请参考 构建产物目录。
本地验证
在项目中执行 pnpm run serve 即可在本地验证构建产物是否正常运行：
$ pnpm run serve
Modern.js Framework
info Starting production server...
> Local: http://localhost:8080/
> Network: http://192.168.0.1:8080/在浏览器中打开 http://localhost:8000/，内容应该和 pnpm run dev 时一致。
部署
本地验证完成后，可以参考 部署 一节，将项目部署到服务器上。