Guide
Tutorials
Configure
API
Community
Guide
Tutorials
Configure
API
Community

Quick Start

Environment

Node.js

Before getting started, you will need to install Node.js, and ensure that your Node.js version is higher than 16.2.0. We recommend using the LTS version of Node.js 18.

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

node -v

If you do not have Node.js installed in your current environment, or the installed version is lower than 16.2.0, you can use nvm or fnm to install the required version.

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

# Install the long-term support version of Node.js 18
nvm install 18 --lts

# Make the newly installed Node.js 18 as the default version
nvm alias default 18

# Switch to the newly installed Node.js 18
nvm use 18
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.

pnpm

It is recommended to use pnpm to manage dependencies:

npm install -g pnpm@8
NOTE

Modern.js also supports dependency management with yarn and npm.

Installation

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:

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

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

npx @modern-js/create@latest myapp

Initialize

@modern-js/create provides an interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:

? Please select the type of project you want to create: Web App
? Please select the programming language: TS
? Please select the package manager: pnpm
? Please select the bundler: webpack

After create the project, Modern.js will automatically install dependencies and create a git repository.

[INFO] dependencies are automatically installed
[INFO] git repository has been automatically created
[INFO] Success！
You can run the following command in the directory of the new project:
pnpm run dev          # Starting dev server
pnpm run build        # Build the app for production
pnpm run serve        # Preview the production build locally
pnpm run lint         # Run ESLint and automatically fix problems
pnpm run new          # Enable optional features or add a new entry

Now, the project structure is as follows:

. ├── 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

Development

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

$ 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/

Open http://localhost:8000/ 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:

import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  runtime: {
    router: true,
  },
  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 Modern.js Core, providing capabilities for configuration parsing, plugin loading, and more.
  • It integrates Modern.js Builder, providing build capabilities.
  • It integrates Modern.js Server, providing capabilities for development and production servers.
  • It integrates some commonly used plugins, such as plugin-lint, plugin-data-loader, and more.

@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:

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:

$ 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

By default, the build artifacts are generated in dist/, with the following directory structure:

dist ├── html │   └── main ├── 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.

Verify

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

$ pnpm run serve

> modern serve

info    Starting production server...

  > Local:    http://localhost:8080/
  > Network:  http://192.168.0.1:8080/

Open http://localhost:8000/ in the browser, and the content should be consistent with that of pnpm run dev.

Deployment

After local verification, you can organize the artifacts in dist/ into the structure required by the server for deployment.