> 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 v20.19.5. **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 is lower than v20.19.5, 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
mise use pnpm@11.24.0
```

:::note
Modern.js also supports dependency management with `yarn` and `npm`.

:::

## Installation

## Initialize

UltraModern.js provides the BleedingDev create package to create SuperApp
workspaces. It does not require global installation and can be run on-demand
using `pnpm dlx`.

The supported pnpm command is the scoped package specifier:
`pnpm dlx @bleedingdev/modern-js-ultramodern-create <target>`. Do not shorten it
to `pnpm dlx modern-js-ultramodern-create`; there is no unscoped package by
that name.

You can initialize the empty directory you are already in:

```bash
mkdir myapp && cd myapp
pnpm dlx @bleedingdev/modern-js-ultramodern-create .
```

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

```bash
pnpm dlx @bleedingdev/modern-js-ultramodern-create my-super-app
```

To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):

```bash
pnpm dlx @bleedingdev/modern-js-ultramodern-create my-super-app --workspace
```

The BleedingDev create package will directly create the application without providing an interactive Q & A interface:

```bash
🚀 Welcome to UltraModern.js

📦 Creating project "my-super-app"...

✨ Project created successfully! 🎉

📋 Next, you can run the following commands:

📁 Enter the project directory:

  cd my-super-app

🔧 Initialize Git repository:

  git init

📥 Install project dependencies:

  pnpm install

⚡ Start the development server:

  pnpm start
```

Now, the project structure is as follows:

```
.
├── apps
│   └── shell-super-app
├── package.json
├── packages
│   ├── shared-contracts
│   ├── shared-design-tokens
│   └── shared-effect-client
├── scripts
├── topology
└── verticals
```

The default workspace starts shell-only and installs the published BleedingDev
package aliases.

From a generated SuperApp workspace, add a business MicroVertical in place:

```bash
pnpm dlx @bleedingdev/modern-js-ultramodern-create transportation --vertical
```

The `--vertical` command mutates the current workspace: it adds the vertical
package and wires topology, ownership metadata, shell Module Federation,
development overlays, package dependencies, generated contracts, route-owned
i18n, CSS isolation, and the Effect BFF/client surface.

The lower-level `--ultramodern-package-*` flags are reserved for release
engineering and local package-source testing. BleedingDev packages are published
through GitHub Actions trusted publishing; do not publish them manually from a
developer machine.

## 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 an UltraModern.js project created using `@bleedingdev/modern-js-ultramodern-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.