> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Quick Start

## Environment

### Node.js

Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v22.18.0. **We recommend using the LTS version of Node.js 22.**

You can check the currently used Node.js version with the following command:

```bash
node -v
```

If you do not have Node.js installed in your current environment, or the installed version does not meet this requirement, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.

Here is an example of how to install the Node.js 22 LTS version via nvm:

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

:::tip 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](https://pnpm.io/installation) to manage dependencies:

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

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

You can also create a project directly in a new directory:

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

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

```bash
🚀 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 dev
```

Now, the project structure is as follows:

```
.
├── modern.config.ts
├── package.json
├── README.md
├── rstack.config.mts
├── src
│   ├── modern.runtime.ts
│   └── routes
│       ├── index.css
│       ├── layout.tsx
│       └── page.tsx
└── tsconfig.json
```

New standalone projects use [Rstack CLI](https://rstack.rs/) for linting and formatting:

```bash
pnpm check
pnpm format
```

## Development

Run `pnpm run dev` in the project to start the project:

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

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

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

```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/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](/guides/basic-features/output-files.md).

## Verify

Run `pnpm run serve` in the project to verify whether the build artifacts run normally locally:

```bash
$ 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](/guides/basic-features/deploy.md) section to deploy the project to the server.