@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/guides/basic-features/testing/rstest.md

@@ -0,0 +1,251 @@
+# Rstest
+
+[Rstest](https://rstest.rs) is a testing framework developed by the Rspack team and built on top of Rspack for fast test execution.
+
+This guide explains how to integrate Rstest with Modern.js for web app testing.
+
+## Quick Start
+
+Install the base dependencies first:
+
+
+```sh [npm]
+npm add @rstest/core @modern-js/adapter-rstest -D
+```
+
+```sh [yarn]
+yarn add @rstest/core @modern-js/adapter-rstest -D
+```
+
+```sh [pnpm]
+pnpm add @rstest/core @modern-js/adapter-rstest -D
+```
+
+```sh [bun]
+bun add @rstest/core @modern-js/adapter-rstest -D
+```
+
+```sh [deno]
+deno add npm:@rstest/core npm:@modern-js/adapter-rstest -D
+```
+
+Then create `rstest.config.ts`:
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+});
+```
+
+`@modern-js/adapter-rstest` lets Rstest inherit your existing Modern.js config so your test setup stays aligned with your app.
+
+For more configuration details, refer to the [Rstest configuration documentation](https://rstest.rs/config).
+
+You can run tests with `npx rstest`, or add a script in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "rstest"
+  }
+}
+```
+
+## Testing Web UI
+
+For web UI tests in Modern.js, there are two common approaches:
+
+- Use Rstest browser mode, which runs tests in a real browser. This is the recommended option in most cases, although it is currently experimental.
+- Use a simulated DOM environment with `happy-dom` and Testing Library. This matches the default web test environment provided by `@modern-js/adapter-rstest`.
+
+We generally recommend browser mode because it uses real browser APIs and behavior, supports cases that simulated DOM environments cannot fully cover, and offers a better debugging experience when UI behavior does not match expectations.
+
+### Browser mode (experimental)
+
+If you want to test in a real browser instead of a simulated DOM, install the browser mode dependencies:
+
+
+```sh [npm]
+npm add @rstest/browser @rstest/browser-react playwright -D
+```
+
+```sh [yarn]
+yarn add @rstest/browser @rstest/browser-react playwright -D
+```
+
+```sh [pnpm]
+pnpm add @rstest/browser @rstest/browser-react playwright -D
+```
+
+```sh [bun]
+bun add @rstest/browser @rstest/browser-react playwright -D
+```
+
+```sh [deno]
+deno add npm:@rstest/browser npm:@rstest/browser-react npm:playwright -D
+```
+
+Then enable browser mode in `rstest.config.ts`:
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  browser: {
+    enabled: true,
+    provider: 'playwright',
+  },
+});
+```
+
+Example test:
+
+```tsx title="__tests__/page.browser.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { page } from '@rstest/browser';
+import { render } from '@rstest/browser-react';
+import { expect, test } from '@rstest/core';
+import Page from '../routes/page';
+
+test('Page', async () => {
+  await render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  await expect.element(
+    page.getByRole('heading', { level: 1, name: 'Home' }),
+  ).toBeVisible();
+});
+```
+
+For more browser mode setup, Locator APIs, and assertions, refer to the [Rstest documentation](https://rstest.rs/guide/browser-testing/).
+
+### DOM simulation with `happy-dom`
+
+Install the DOM testing dependencies:
+
+
+```sh [npm]
+npm add happy-dom @testing-library/react @testing-library/dom -D
+```
+
+```sh [yarn]
+yarn add happy-dom @testing-library/react @testing-library/dom -D
+```
+
+```sh [pnpm]
+pnpm add happy-dom @testing-library/react @testing-library/dom -D
+```
+
+```sh [bun]
+bun add happy-dom @testing-library/react @testing-library/dom -D
+```
+
+```sh [deno]
+deno add npm:happy-dom npm:@testing-library/react npm:@testing-library/dom -D
+```
+
+Update `rstest.config.ts` to use `happy-dom`:
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  testEnvironment: 'happy-dom',
+});
+```
+
+First, create a simple page for testing:
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Page = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Page;
+```
+
+Then add a test case:
+
+```tsx title="__tests__/page.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { expect, test } from '@rstest/core';
+import { render, screen } from '@testing-library/react';
+import Page from '../routes/page';
+
+test('Page', () => {
+  render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
+});
+```
+
+## Running Test Cases
+
+Execute the `test` command above to run your tests:
+
+```bash
+✓ __tests__/page.test.tsx (1)
+  ✓ Page
+
+ Test Files 1 passed
+      Tests 1 passed
+   Duration 510ms (build 145ms, tests 365ms)
+```
+
+## Node Mode
+
+If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.
+
+Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.
+
+## Migrating from Existing Projects
+
+If your project already uses Jest or Vitest, refer to the official Rstest migration guides:
+
+- [Migrate from Jest to Rstest](https://rstest.rs/guide/migration/jest)
+- [Migrate from Vitest to Rstest](https://rstest.rs/guide/migration/vitest)
+
+We recommend installing the `migrate-to-rstest` skill first, then copying this prompt to your coding agent. It keeps the Modern.js `@modern-js/adapter-rstest` integration during migration:
+
+
+For your Agent
+
+Migrate to Rstest
+
+Copy this prompt and send it to your coding agent.
+
+Copy Prompt
+
+Migrate this Modern.js project from Jest or Vitest to Rstest.
+
+First install and use the migrate-to-rstest skill. If it is not installed, install it with:
+npx skills add rstackjs/agent-skills --skill migrate-to-rstest
+
+Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
+- Jest: https://rstest.rs/guide/migration/jest
+- Vitest: https://rstest.rs/guide/migration/vitest
+
+Modern.js-specific requirement:
+- Install and use @modern-js/adapter-rstest together with @rstest/core.
+- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
+- Reuse the Modern.js app configuration with extends: withModernConfig().
+- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.

package/docs/guides/concept/builder.md

@@ -0,0 +1,37 @@
+# Build Engine
+
+Modern.js internally encapsulates [Rsbuild](https://v2.rsbuild.rs/), using Rspack as the bundler.
+
+::: tip What is Rsbuild?
+Rsbuild is a build tool based on Rspack. It is an enhanced Rspack CLI, easy-to-use, and ready-to-use out of the box.
+:::
+
+## Build Architecture
+
+From the building perspective, Modern.js can be divided into three-layers, from top to bottom:
+
+- Upper-level framework: Modern.js.
+- Build tool: Rsbuild.
+- Bundler: Rspack.
+
+
+## Build Documentation
+
+The documentation address of Rsbuild is: [https://v2.rsbuild.rs/](https://v2.rsbuild.rs/)
+
+In this documentation, you can learn about the detailed introduction of Rsbuild, and you can also find complete usage guides for various building capabilities.
+
+If you want to understand the use of build configurations, it is recommended that you read the Modern.js documentation first, because the build configurations and defaults in Modern.js are not exactly the same as Rsbuild.
+
+## Build Plugins
+
+In Modern.js, you can register Rspack plugins or Rsbuild plugins:
+
+- Rspack plugins: Configured through [tools.bundlerChain](/configure/app/tools/bundler-chain.md).
+- Rsbuild plugins: Configured through [builderPlugins](/configure/app/builder-plugins.md).
+
+## Build Capabilities
+
+Rsbuild provides rich build capabilities, including JavaScript compilation, CSS compilation, static assets processing, code hot update, code compression, TS type checking, and dozens of other capabilities.
+
+We recommend that you read [「Rsbuild - All Features」](https://v2.rsbuild.rs/guide/start/features) to learn about all the features provided by Rsbuild.

package/docs/guides/concept/entries.md

@@ -0,0 +1,319 @@
+# Page Entry
+
+Through this chapter, you can understand the entry conventions in Modern.js and how to customize entries.
+
+## What is Entry
+
+**Entry refers to the starting module of a page.**
+
+In a Modern.js application, each entry corresponds to an independent page and a server-side route. By default, Modern.js automatically determines page entries based on directory conventions, and also supports customizing entries through configuration options.
+
+Many configuration options provided by Modern.js are divided by entry, such as page title, HTML template, page meta information, whether to enable SSR/SSG, server-side routing rules, etc. If you want to learn more about the technical details of entries, please refer to the [In-Depth](#in-depth) chapter.
+
+## Single Entry and Multiple Entries
+
+The application initialized by Modern.js is a single-entry application with the following structure:
+
+```
+.
+├── src
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+└── tsconfig.json
+```
+
+In a Modern.js application, you can easily switch from single entry to multiple entries. To manually create multiple entries, follow these steps:
+
+
+1. **Move the original entry code to a directory named after the `name` field in `package.json`**
+
+   Assuming the `name` in `package.json` is `myapp`, you need to move the `src/routes/` directory to `src/myapp/routes/`:
+
+```bash
+# Create new directory
+mkdir -p src/myapp
+# Move original entry code
+mv src/routes src/myapp/routes
+```
+
+2. **Create a new entry directory**
+
+   Create a new entry directory, for example `new-entry`:
+
+```bash
+# Create new entry directory
+mkdir -p src/new-entry/routes
+```
+
+3. **Create necessary files in the new entry directory**
+
+   Create basic files in the `routes/` directory of the new entry:
+
+```bash
+# Create basic files (adjust content as needed)
+touch src/new-entry/routes/index.css
+touch src/new-entry/routes/layout.tsx
+touch src/new-entry/routes/page.tsx
+```
+
+After completing the above steps, the `src/` directory structure will be as follows:
+
+```bash
+.
+├── myapp    # Original entry
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry # New entry
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+Modern.js will use the entry with the same name as the `name` field in `package.json` as the main entry. The route of the main entry is `/`, and the route of other entries is `/{entryName}`. For example, when the `name` in `package.json` is `myapp`, `src/myapp` will be the main entry of the application.
+
+You can execute `pnpm run dev` to start the development server. At this time, you can see that a new route named `/new-entry` has been added, and the routes of the original pages have not changed.
+
+:::note
+The concepts of **single entry/multiple entry** and **SPA/MPA** are not equivalent. The former is about how to configure and package the application, while the latter is a pattern for organizing front-end applications. Each entry can be SPA or non-SPA.
+:::
+
+## Entry Types
+
+Modern.js supports three entry types, each with different use cases and characteristics. Choosing the appropriate entry type can help you better organize your code.
+
+### How to Identify Entries
+
+Modern.js automatically scans directories to identify entries that meet the criteria. A directory is recognized as an entry if it meets **one of the following three conditions**:
+
+1. **Has a `routes/` directory** → Convention routing entry
+2. **Has an `App.tsx?` file** → Self-controlled routing entry
+3. **Has an `entry.tsx?` file** → Custom entry
+
+:::tip 入口扫描逻辑
+
+- 如果 `src/` 本身满足入口条件 → 单入口应用
+- 如果 `src/` 不满足条件 → 扫描 `src/` 下的子目录 → 多入口应用
+- 单入口应用中，默认入口名为 `index`
+
+:::
+
+:::tip Custom scanning directory
+You can modify the directory for identifying entries through [source.entriesDir](/configure/app/source/entries-dir.md).
+
+:::
+
+
+Next, we will introduce the usage of each entry type in detail.
+
+### Convention Routing
+
+If there is a `routes/` directory in the entry, we call this entry a convention routing entry. Modern.js will scan the files under `routes/` during startup and automatically generate client-side routes (react-router) based on file conventions. For example:
+
+```bash
+src/
+└── routes/
+    ├── layout.tsx    # Layout component (optional)
+    ├── page.tsx      # Homepage component (/ route)
+    ├── about/
+    │   └── page.tsx  # About page (/about route)
+    └── blog/
+        ├── page.tsx  # Blog list page (/blog route)
+        └── [id]/
+            └── page.tsx  # Blog detail page (/blog/:id route)
+```
+
+Component correspondence
+
+| File                        | Route         | Description                   |
+| --------------------------- | ------------- | ----------------------------- |
+| `routes/layout.tsx`         | Global layout | Outer container for all pages |
+| `routes/page.tsx`           | `/`           | Homepage                      |
+| `routes/about/page.tsx`     | `/about`      | About page                    |
+| `routes/blog/[id]/page.tsx` | `/blog/:id`   | Dynamic route page            |
+
+For more details, please refer to [Routing Solution](/guides/basic-features/routes/routes.md#convention-routing).
+
+### Self-controlled Routing
+
+If there is an `App.tsx?` file in the entry, this entry is a self-controlled routing entry. This method gives developers complete routing control.
+
+```bash
+.
+├── src
+│   └── App.tsx
+```
+
+For the entry defined as `src/App.tsx`, Modern.js does not perform additional routing operations. Developers can use the [React Router v7](https://reactrouter.com/en/main) API to set up client-side routes, or not set up client-side routes. For example, the following code sets up client-side routes in the application:
+
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+:::note
+We recommend developers use convention routing. Modern.js provides a series of optimizations in resource loading and rendering for convention routing by default and offers built-in SSR capabilities. When using self-controlled routing, these capabilities need to be encapsulated by developers themselves.
+:::
+
+### Custom Entry
+
+By default, when using convention routing or self-controlled routing, Modern.js will automatically handle rendering. If you want to customize this behavior, you can implement it through a custom entry file.
+
+:::tip
+Custom entries can coexist with convention routing and self-controlled routing entries, customizing the application initialization logic.
+
+:::
+
+If there is an `entry.tsx` file in the entry, Modern.js will no longer control the application's rendering process. You can call the `createRoot` and `render` functions in the `entry.tsx` file to complete the application entry logic.
+
+```tsx title="src/entry.tsx"
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+// Create root component
+const ModernRoot = createRoot();
+
+// Render to DOM
+render(<ModernRoot />);
+```
+
+In the code above, the component returned by the `createRoot` function is the component generated from the `routes/` directory or exported by `App.tsx`. The `render` function is used to handle rendering and mounting components. For example, if you want to execute some asynchronous tasks before rendering, you can implement it like this:
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+  // some async request
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+If you don't want to use any of Modern.js's runtime capabilities, you can also mount the component to the DOM node yourself, for example:
+
+```js title=src/entry.tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+const container = document.getElementById('root');
+
+if (container) {
+  const root = createRoot(container);
+  root.render(<App />);
+}
+```
+
+In this mode, **you will not be able to use Modern.js framework's runtime capabilities**, such as:
+
+- Convention routing, i.e., routing based on files under `src/routes`
+- Server-Side Rendering (SSR)
+- Internationalization (i18n)
+- Module Federation
+
+## Specifying Entries in Configuration File
+
+In some cases, you may need to customize the entry configuration instead of using the entry conventions provided by Modern.js.
+
+For example, if you need to migrate a non-Modern.js application to Modern.js, and it is not structured according to Modern.js's directory structure, there might be some migration costs involved in changing it to the conventional structure. In such cases, you can use custom entries.
+
+Modern.js provides the following configuration options that you can set in [modern.config.ts](/configure/app/usage.md):
+
+- [source.entries](/configure/app/source/entries.md): Used to set custom entry objects.
+- [source.disableDefaultEntries](/configure/app/source/disable-default-entries.md): Used to disable Modern.js's default entry scanning behavior. When you use custom entries, parts of your project structure might coincidentally match the Modern.js conventional directory structure, but you may not want Modern.js to generate entry configurations for them. Enabling this option can help avoid this issue.
+
+### Example
+
+Here is an example of a custom entry. You can also refer to the documentation of the corresponding configuration options for more usage.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      // Specify an entry named 'my-entry'
+      'my-entry': {
+        // Path to the entry module
+        entry: './src/my-page/index.tsx',
+        // Disable automatic generation of entry code by Modern.js
+        disableMount: true,
+      },
+    },
+    // Disable entry scanning behavior
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## In-Depth
+
+Pages usually correspond to HTML output files, meaning each additional entry will eventually generate a corresponding HTML file in the output. The modules imported by the entry will be compiled and packaged into multiple Chunk outputs. For example, JavaScript modules may ultimately generate several file outputs similar to `dist/static/js/index.ea39u8.js`.
+
+It's important to distinguish the relationships between concepts such as entry and route:
+
+- **Entry**: Contains multiple modules used for startup execution.
+- **Client Router**: In Modern.js, it is usually implemented by `react-router`, using the History API to determine which React component to load and display based on the browser's current URL.
+- **Server Router**: Determines what content the server returns based on the request URL. For traditional multi-page applications, different URLs usually return different HTML pages directly. For single-page applications that use client-side routing, the server generally falls back non-static asset requests to the entry HTML, and then the frontend takes over subsequent route matching and page rendering.
+
+Their corresponding relationships are as follows:
+
+- Each website project can contain multiple entries
+- Each entry contains several modules (source code files)
+- Each entry usually corresponds to one HTML file output and several other outputs
+- Each HTML file can contain multiple client-side routing solutions (for example, using both `react-router` and `@tanstack/react-router` in the same page)
+- Each HTML file can be mapped to multiple server-side routes
+- Each HTML file can contain multiple client-side routing solutions, and when accessing different routes of a single-entry application, the same HTML file is actually used
+
+## Common Issues
+
+1. **Does each client route defined by `react-router` generate a separate HTML file?**
+
+No. Each entry usually only generates one HTML file. If multiple client routing systems are defined in a single entry, they will share this one HTML file.
+
+2. **Does each `page.tsx` file in the `routes/` directory of convention routing generate an HTML file?**
+
+No. Convention routing is a client-side routing solution implemented based on `react-router`. Its convention is that each `page.tsx` file under the `routes/` directory corresponds to a client-side route of `react-router`. `routes/` itself serves as a page entry, corresponding to one HTML file in the final output.
+
+3. **Do Server-Side Rendering (SSR) projects build multiple HTML outputs?**
+
+When using server-side rendering applications, it is not necessary to generate an HTML output at build time. It can only include server-side JavaScript output for rendering. At this time, `react-router` will run and schedule routes on the server side, rendering and responding with HTML content on each request.
+
+However, Modern.js will still generate a complete client-side output containing HTML files for each entry at build time, which can be used to downgrade to client-side rendering when server-side rendering fails.
+
+Another special case is a project using Static Site Generation (SSG). Even if it is a single-entry SSG application built with convention routing, Modern.js will generate a separate HTML file for each `page.tsx` file outside the Rspack process.
+
+It should be noted that even when server-side rendering is enabled, React usually still needs to execute the hydration phase and run `react-router` routing on the frontend.
+
+4. **Are there exceptions where single-entry applications output multiple HTML files?**
+
+You can configure [html-rspack-plugin](https://rspack.rs/zh/plugins/rspack/html-rspack-plugin#%E7%94%9F%E6%88%90%E5%A4%9A%E4%B8%AA-html-%E6%96%87%E4%BB%B6) to generate multiple HTML outputs for each entry, or have multiple entries share one HTML output.
+
+5. **What is a Multi-Page Application (Multi-Page Application)?**
+
+The "page" in a Multi-Page Application refers to a static HTML file.
+
+Generally, any web application that contains multiple entries and multiple HTML file outputs can be called a multi-page application.
+
+In a narrow sense, a multi-page application may not contain client-side routing and only navigates between static HTML pages through elements like `<a>` tags. However, in practice, multi-page applications often need to configure client-side routing for their entries to meet different needs.
+
+Conversely, a single-entry application that defines multiple routes through `react-router` is called a Single Page Application because it only generates one HTML file output.

package/docs/guides/concept/server.md

@@ -0,0 +1,35 @@
+# Web Server
+
+Modern.js provides an integrated Web server for applications that can run in any container environment with Node.js. Whether executing the `dev` command in a local development environment, running the `build && serve` commands in a production environment, or using the official deployment solution, it all runs through this Web server to host the application.
+
+## Underlying Dependencies
+
+Modern.js builds its Web server based on the [Hono framework](https://hono.dev/). Hono is a small, simple, and ultra-fast web standard-based framework that can run on any JavaScript runtime.
+
+## Development & Production
+
+The Web server flow in both Modern.js development and production environments is entirely isomorphic, so you don't need to worry about differences between them.
+
+As mentioned in the [Build Tools](/guides/concept/builder.md) section, Modern.js' underlying build capability is provided by Rsbuild, and some server-side capabilities in the development environment are coupled with the build tools, such as HMR. Modern.js needs to reuse these capabilities of the Rsbuild Dev Server.
+
+In the development environment, Modern.js directly uses the middlewares provided by Rsbuild, which includes capabilities needed during the development stage such as HMR and Proxy. Additionally, Modern.js provides capabilities such as Mock, routing, and rendering on top of this:
+
+![Server](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/web-server-modern.jpeg)
+
+Therefore, in Modern.js, the development environment merely adds middleware to the production environment. All capabilities of the production environment are also applicable in the development environment, ensuring no fragmentation between the two.
+
+:::tip
+Static asset files can be directly hosted by Modern.js' server, but it is highly recommended to upload these files to a CDN in a production environment.
+:::
+
+## Running in CI Environments
+
+Modern.js supports running built artifacts in any Node.js environment. Typically, the CI environment has already installed all application dependencies.
+
+You can run the [`modern build`](/apis/app/commands.md#modern-build) command to build the application and the [`modern serve`](/apis/app/commands.md#modern-serve) command to run the Web server, starting the Modern.js application.
+
+## Running in Production Environments
+
+When deploying to production, the artifact size should be as small as possible. The aforementioned method for running in CI environments keeps all artifacts from the original project. Therefore, it is not recommended to run the application using the above commands in a production environment.
+
+Modern.js offers a standalone deployment solution. When running the [`modern deploy`](/apis/app/commands.md#modern-deploy) command, the artifacts will include an entry file for running the Web server.