快速上手

环境准备

Node.js

在开始使用前,你需要安装 Node.js,并保证 Node.js 版本不低于 16.2.0,我们推荐使用 Node.js 18 的 LTS 版本

你可以通过以下命令检查当前使用的 Node.js 版本:

node -v

如果你当前的环境中尚未安装 Node.js,或是安装的版本低于 16,可以通过 nvmfnm 安装需要的版本。

下面是通过 nvm 安装 Node.js 18 LTS 版本的例子:

# 安装 Node.js 18 的长期支持版本
nvm install 18 --lts

# 将刚安装的 Node.js 18 设置为默认版本
nvm alias default 18

# 切换到刚安装的 Node.js 18
nvm use 18
nvm 和 fnm

nvm 和 fnm 都是 Node.js 版本管理工具。相对来说,nvm 较为成熟和稳定,而 fnm 是使用 Rust 实现的,比 nvm 提供了更好的性能。

此外,在安装 nvm 或 fnm 后,然后只要仓库根目录下有内容为 lts/hydrogen.nvmrc 文件,进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。

pnpm

推荐使用 pnpm 来管理依赖:

npm install -g pnpm@8
NOTE

Modern.js 同样支持使用 yarnnpm 进行依赖管理。

安装

Modern.js 提供了 @modern-js/create 工具来创建项目,不需要全局安装,直接使用 npx 按需运行即可。

你可以在已有的空目录来创建项目:

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

也可以直接用新目录创建项目:

npx @modern-js/create@latest myapp

初始化项目

@modern-js/create 会提供一个可交互的问答界面,根据结果初始化项目,按照默认的选择进行初始化:

? 请选择你想创建的工程类型 Web 应用
? 请选择开发语言 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:

modern.config.ts
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
    }),
  ],
});

重新执行 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

modern.config.ts
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 时一致。

部署

本地验证完成后,可以参考 部署 一节,将项目部署到服务器上。