在开始使用前,你需要安装 Node.js,并保证 Node.js 版本不低于 14.17.6,我们推荐使用 Node.js 18 的 LTS 版本。
你可以通过以下命令检查当前使用的 Node.js 版本:
node -v
如果你当前的环境中尚未安装 Node.js,或是安装的版本低于 14.17.6,可以通过 nvm 或 fnm 安装需要的版本。
下面是通过 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 都是 Node.js 版本管理工具。相对来说,nvm 较为成熟和稳定,而 fnm 是使用 Rust 实现的,比 nvm 提供了更好的性能。
此外,在安装 nvm 或 fnm 后,然后只要仓库根目录下有内容为 lts/hydrogen
的 .nvmrc
文件,进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
推荐使用 pnpm 来管理依赖:
npm install -g pnpm@8
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
会提供一个可交互的问答界面,根据结果初始化项目,按照默认的选择进行初始化:
? 请选择你想创建的工程类型 Web 应用
? 请选择开发语言 TS
? 请选择包管理工具 pnpm
? 请选择构建工具 webpack
在生成项目后,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
info Starting dev server...
ready Client compiled in 50 ms
> 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({
runtime: {
router: true,
},
server: {
ssr: true,
},
plugins: [appTools()],
});
重新执行 pnpm run dev
,在浏览器 Network 菜单中,可以发现项目已经在服务端完成了页面渲染。
在新创建的工程中,默认会安装 @modern-js/app-tools
npm 包,它是 Modern.js 框架的核心包,主要提供以下能力:
modern dev
, modern build
等常用的 CLI 命令。plugin-lint
、plugin-data-loader
等。@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
info Staring production build...
ready Client compiled in 50 ms
info Production file sizes:
File Size Gzipped
dist/static/js/lib-react.09721b5c.js 152.6 kB 49.0 kB
dist/html/main/index.html 5.8 kB 2.5 kB
dist/static/js/main.3568a38e.js 3.5 kB 1.4 kB
dist/static/css/main.03221f72.css 1.4 kB 741 B
构建产物默认生成到 dist/
,目录结构如下:
dist
├── html
│ └── main
├── modern.config.json
├── route.json
├── routes-manifest.json
└── static
├── css
└── js
如果你需要自定义构建产物的目录,请参考 构建产物目录。
在项目中执行 pnpm run serve
即可在本地验证构建产物是否正常运行:
$ pnpm run serve
> modern serve
Starting production server...
> Local: http://localhost:8080/
> Network: http://192.168.0.1:8080/
在浏览器中打开 http://localhost:8000/
,内容应该和 pnpm run dev
时一致。
本地验证完成后,可以将 dist/
下的产物整理成服务器需要的结构,进行部署。