---
title: 快速上手
sidebar_position: 2
---

# 快速上手

## 环境准备

import Prerequisites from '@site-docs/components/prerequisites';

<Prerequisites />

## 安装

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

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

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

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

```bash
npx @modern-js/create@latest myapp
```

## 初始化项目

import InitApp from '@site-docs/components/init-app';

<InitApp />

## 启动项目

import DebugApp from '@site-docs/components/debug-app';

<DebugApp />

## 使用配置

通过 `@modern-js/create` 创建的 Modern.js 项目中，会默认生成 `modern.config.ts` 文件。

你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：

```ts title="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`：

```ts title="modern.config.ts"
import { appTools, defineConfig } from '@modern-js/app-tools';

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

## 构建项目

在项目中执行 `pnpm run build` 即可构建项目生产环境产物：

```bash
$ 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
```

> 如果你需要自定义构建产物的目录，请参考 [构建产物目录](/guides/basic-features/output-files)。

## 本地验证

在项目中执行 `pnpm run serve` 即可在本地验证构建产物是否正常运行：

```bash
$ 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` 时一致。

## 部署

import Deploy from '@site-docs/components/deploy';

<Deploy />
