@modern-js/main-doc 2.58.3 → 2.60.0

package/docs/en/guides/basic-features/static-assets/_meta.json

@@ -0,0 +1 @@
+["json-files", "svg-assets", "wasm-assets"]

package/docs/en/guides/basic-features/static-assets.mdx

@@ -21,7 +21,7 @@ The following are the formats supported by Modern.js by default:
 If you need to import assets in other formats, please refer to [Extend Asset Types](#extend-asset-types).
 
 :::tip SVG images
-SVG image is a special case. Modern.js support convert SVG to React components, so SVG is processed separately. For details, see [Import SVG Assets](/guides/basic-features/svg-assets.html).
+SVG image is a special case. Modern.js support convert SVG to React components, so SVG is processed separately. For details, see [Import SVG Assets](/guides/basic-features/static-assets/svg-assets.html).
 :::
 
 ## Import Assets in JS file
@@ -76,7 +76,7 @@ console.log(largeImage); // "/static/largeImage.6c12aba3.png"
 console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."
 ```
 
-For a more detailed introduction to asset inlining, please refer to the [Static Asset Inlining](/guides/advanced-features/inline-assets) chapter.
+For a more detailed introduction to asset inlining, please refer to the [Static Asset Inlining](/guides/advanced-features/page-performance/inline-assets) chapter.
 
 ## Output Files
 

package/docs/en/guides/basic-features/testing/_meta.json

@@ -0,0 +1 @@
+["playwright", "vitest", "jest", "cypress"]

package/docs/en/guides/basic-features/testing/cypress.mdx

@@ -0,0 +1,95 @@
+# Cypress
+
+Cypress is a framework for E2E testing and component testing.
+
+To use Cypress in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm install -D cypress", yarn: "yarn add -D cypress", pnpm: "pnpm install -D cypress" }} />
+
+Next, create a `cypress.config.ts` file and add the following content:
+
+```ts
+import { defineConfig } from 'cypress'
+ 
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {},
+  },
+})
+```
+
+## Writing Test Cases
+
+Now, use Cypress to write an E2E test case by first creating two Modern.js pages.
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+```tsx title="routes/about/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>About</h1>
+    <Link to="/">Home</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Next, create the test case file:
+
+```ts title="cypress/e2e/app.cy.ts"
+describe('Navigation', () => {
+  it('should navigate to the about page', () => {
+    // Start from the index page
+    cy.visit('http://localhost:8080/')
+ 
+    // Find a link with an href attribute containing "about" and click it
+    cy.get('a[href*="about"]').click()
+ 
+    // The new url should include "/about"
+    cy.url().should('include', '/about')
+ 
+    // The new page should contain an h1 with "About"
+    cy.get('h1').contains('About')
+  })
+})
+```
+
+The test file may lack type definitions for the API. You can refer to the [Cypress - Typescript](https://docs.cypress.io/guides/tooling/typescript-support#Configure-tsconfigjson) documentation to resolve this.
+
+You can add the command to your `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "cypress open"
+  }
+}
+```
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```bash
+DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
+```
+
+Cypress will open a headless browser. Following the prompts, you can find the corresponding test files and automatically run the E2E tests:
+
+![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

package/docs/en/guides/basic-features/testing/jest.mdx

@@ -0,0 +1,148 @@
+# Jest
+
+Jest is a JavaScript testing framework that is primarily used with React Testing Library for unit testing and Snapshot testing.
+
+To use Jest in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ 
+  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom", 
+  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom", 
+  pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
+}} />
+
+Next, you can run the following commands to automatically initialize Jest in your project and generate a basic `jest.config.[jt]s` configuration:
+
+<PackageManagerTabs command={{ 
+  npm: "npm init jest@latest", 
+  yarn: "yarn create jest@latest", 
+  pnpm: "pnpm create jest@latest"
+}} />
+
+## Configuration File
+
+:::note
+This section will use `.ts` files for Jest testing.
+:::
+
+Compared to other testing frameworks, Jest requires more configuration at the build level, such as handling JSX and ESM syntax. Therefore, you need to install some additional dependencies:
+
+<PackageManagerTabs command={{ 
+  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript", 
+  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript", 
+  pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
+}} />
+
+### Configure Jest
+
+You need to further configure the `jest.config.ts` file to allow Jest to correctly compile and run test cases. Here is a basic configuration:
+
+```ts title="jest.config.ts"
+import type { Config } from 'jest';
+
+const config: Config = {
+  coverageProvider: 'babel',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;
+```
+
+In the configuration, the `transformIgnorePatterns` is set to an empty array, meaning that all files will be compiled. If you want to speed up the test run, you can configure it as needed.
+
+The `setupFilesAfterEnv` will be executed at startup. In `jest.setup.ts`, you can import `@testing-library/jest-dom`, which includes a set of convenient custom matchers, such as `.toBeInTheDocument()`, to make writing tests easier:
+
+```ts title="jest.setup.ts"
+import '@testing-library/jest-dom';
+```
+
+### Configure Babel
+
+You need to configure Babel to allow Jest to automatically compile JSX and other syntax. Here is a basic configuration:
+
+```js title="babel.config.js"
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    ['@babel/preset-react', { runtime: 'automatic' }],
+    '@babel/preset-typescript',
+  ],
+};
+```
+
+## Writing Test Cases
+
+Now, you can start writing tests. First, add a `test` command in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+Create a simple page for testing:
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Add a test case to check if the page has the expected text:
+
+```tsx title="__tests__/page.test.tsx"
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+describe('Page', () => {
+  it('renders a heading', () => {
+    render(
+      <Router>
+        <Page />
+      </Router>,
+    );
+
+    const heading = screen.getByRole('heading', { level: 1 });
+
+    expect(heading).toBeInTheDocument();
+  });
+});
+```
+
+In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering some route-related components.
+
+:::note
+When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
+:::
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```bash
+ PASS  src/__tests__/page.test.tsx
+  Page
+    ✓ renders a heading (31 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        0.959 s, estimated 1 s
+```

package/docs/en/guides/basic-features/testing/playwright.mdx

@@ -0,0 +1,111 @@
+# Playwright
+
+Playwright is a testing framework that allows you to run tests automatically in Chromium, Firefox, and WebKit environments using a single API. You can use it to **write E2E tests**.
+
+To use Playwright in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm init playwright", yarn: "yarn create playwright", pnpm: "pnpm create playwright" }} />
+
+The above commands will automatically install Playwright dependencies and help you install and configure it in your project through a series of prompts, including adding a `playwright.config.ts` file.
+
+:::info
+Refer to the official Playwright documentation at [Install Playwright](https://playwright.dev/docs/intro#installation) for a more detailed guide.
+:::
+
+After creating with the default configuration, you can see the following files in your project:
+
+```ts title="tests/example.spec.ts"
+import { test, expect } from '@playwright/test';
+
+test('has title', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Expect a title "to contain" a substring.
+  await expect(page).toHaveTitle(/Playwright/);
+});
+
+test('get started link', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Click the get started link.
+  await page.getByRole('link', { name: 'Get started' }).click();
+
+  // Expects page to have a heading with the name of Installation.
+  await expect(
+    page.getByRole('heading', { name: 'Installation' }),
+  ).toBeVisible();
+});
+```
+
+This is the default test file. Now create some new pages and test them.
+
+## Create E2E Tests
+
+First, create two Modern.js pages.
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+```tsx title="routes/about/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>About</h1>
+    <Link to="/">Home</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Next, add test cases to ensure the links on your pages work properly.
+
+```ts title="tests/example.spec.ts"
+import { test, expect } from '@playwright/test'
+
+test('should navigate to the about page', async ({ page }) => {
+  // Start from the index page (the baseURL is set via the webServer in the playwright.config.ts)
+  await page.goto('http://localhost:8080/')
+  // Find an element with the text 'About' and click on it
+  await page.click('text=About')
+  // The new URL should be "/about" (baseURL is used there)
+  await expect(page).toHaveURL('http://localhost:8080/about')
+  // The new page should contain an h1 with "About"
+  await expect(page.locator('h1')).toContainText('About')
+})
+```
+
+## Run Test Cases
+
+Playwright requires your Modern.js server to be running. We recommend running your test cases under production builds; you can run `pnpm run build` and `pnpm run serve` to simulate the production environment locally.
+
+```bash
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.59.30:8080/
+```
+
+After the project is successfully built and running, you can run Playwright cases in another terminal by executing `npx playwright test`:
+
+```bash
+Running 3 tests using 3 workers
+  3 passed (2.0s)
+
+To open last HTML report run:
+
+  npx playwright show-report
+```

package/docs/en/guides/basic-features/testing/vitest.mdx

@@ -0,0 +1,100 @@
+# Vitest
+
+Vitest is a testing framework driven by Vite, which can be used for unit testing in combination with React Testing Library.
+
+To use Vitest in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ 
+  npm: "npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom", 
+  yarn: "yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom", 
+  pnpm: "pnpm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
+  bun: "bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom"
+}} />
+
+Next, you need to create a Vitest configuration file `vitest.config.ts` with the following content:
+
+```ts title="vitest.config.ts"
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+ 
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+  },
+})
+```
+
+For more information about Vitest configuration, you can refer to the [Vitest configuration documentation](https://vitest.dev/config/#configuration).
+
+You can optionally add the `vitest` command to `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+After running this command, Vitest will automatically watch your file changes and rerun the test cases.
+
+## Create Unit Tests
+
+First, create a simple page for testing:
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Add a test case to check if the page has the expected text:
+
+```tsx title="__tests__/page.test.tsx"
+import { expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+test('Page', () => {
+  render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
+});
+```
+
+In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering some route-related components.
+
+:::note
+When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
+:::
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```bash
+✓ src/__tests__/page.test.tsx (1)
+  ✓ Page
+
+Test Files  1 passed (1)
+    Tests  1 passed (1)
+  Start at  15:37:12
+  Duration  999ms (transform 119ms, setup 0ms, collect 365ms, tests 33ms, environment 421ms, prepare 44ms)
+
+
+PASS  Waiting for file changes...
+```

package/docs/en/guides/concept/entries.mdx

@@ -116,6 +116,8 @@ For more information, please refer to [Conventional Routing](/guides/basic-featu
 
 #### Self-controlled Routing
 
+## Manual Routing
+
 If there is an `App.[jt]sx?` file within the entry, we refer to this entry as a self-controlled route. For example:
 
 ```bash
@@ -124,7 +126,9 @@ If there is an `App.[jt]sx?` file within the entry, we refer to this entry as a
 │   └── App.tsx
 ```
 
-In this file, you can define client-side routes or  not to set any client-side routes.
+For entry points defined as `src/App.tsx`, Modern.js does not perform any additional routing operations. Developers can use the [React Router 6](https://reactrouter.com/en/main) API for development, define client-side routes or not to set any client-side routes.
+
+for example, define client-side routes in application:
 
 ```tsx
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
@@ -141,7 +145,10 @@ export default () => {
 };
 ```
 
-For more information, please refer to [Self-controlled Routing](/guides/basic-features/routes.html#self-controlled-routing).
+:::note
+We recommend that developers use conventional routing. Modern.js provides a series of optimizations in resource loading and rendering for conventional routing by default and offers built-in SSR capabilities. When using manual routing, these capabilities need to be encapsulated by developers themselves.
+:::
+
 
 #### Custom Entry
 

package/docs/en/guides/deprecated.md

@@ -13,3 +13,5 @@ The Monorepo solution previously provided by Modern.js was implemented based on
 ## Enabling the test capability with the new command
 
 The test capability previously provided by Modern.js was a simple wrapper based on Jest, which led to issues such as unintuitive Jest configuration and more complex user configuration. In version [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0), the option to enable the test feature in application and module projects has been removed. It is recommended to directly use the testing solutions provided by the community.
+
+Previously, Modern.js provided a comprehensive set of ESLint rules, including @modern-js (for Node.js project linting rules) and @modern-js-app (for frontend project linting rules). In version [v2.60.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.60.0), we officially removed these rule sets. We encourage developers to choose appropriate code standard tools based on their needs, either by directly using ESLint with community-recommended rules or by using Biome to enhance code formatting performance.

package/docs/en/guides/get-started/quick-start.mdx

@@ -57,7 +57,7 @@ export default defineConfig({
     ssr: true,
   },
   plugins: [appTools({
-      bundler: 'webpack', // Set to 'experimental-rspack' to enable rspack ⚡️🦀
+      bundler: 'rspack', // Set to 'webpack' to enable webpack
   }),],
 });
 ```

package/docs/en/guides/get-started/tech-stack.mdx

@@ -60,7 +60,7 @@ During production builds, Modern.js uses [Terser](https://github.com/terser/ters
 
 Modern.js uses [PostCSS](https://postcss.org/) to transform CSS code and enables [autoprefixer](https://github.com/postcss/autoprefixer) by default to add CSS prefixes.
 
-Modern.js supports enabling ["Tailwind CSS"](/en/guides/basic-features/css.html#using-tailwind-css) and is compatible with both Tailwind CSS v2 and v3.
+Modern.js supports enabling ["Tailwind CSS"](/guides/basic-features/css/tailwindcss) and is compatible with both Tailwind CSS v2 and v3.
 
 ## CSS Preprocessors
 
@@ -73,11 +73,11 @@ Modern.js supports three CSS preprocessors: [Sass](https://sass-lang.com/), [Les
 
 Modern.js provides out-of-the-box support for [CSS Modules](https://github.com/css-modules/css-modules), which is implemented internally based on [css-loader](https://www.npmjs.com/package/css-loader).
 
-Please refer to ["Use CSS Modules"](/guides/basic-features/css-modules) for usage instructions.
+Please refer to ["Use CSS Modules"](/guides/basic-features/css/css-modules) for usage instructions.
 
 ## CSS-in-JS
 
-Modern.js supports the use of [styled-components](https://styled-components.com/). Please refer to ["Using CSS-in-JS"](/en/guides/basic-features/css.html#using-css-in-js) for usage instructions.
+Modern.js supports the use of [styled-components](https://styled-components.com/). Please refer to ["Using CSS-in-JS"](/en/guides/basic-features/css/css-in-js) for usage instructions.
 
 If you need to use other CSS-in-JS solutions, you can integrate them into your project on your own.
 
@@ -89,7 +89,7 @@ Additionally, Modern.js provides built-in support for [on-demand import](/config
 
 ## Component Development
 
-Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/en/guides/advanced-features/using-storybook) to enable it.
+Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook) to enable it.
 
 ## Node.js Framework
 

package/docs/en/guides/topic-detail/_meta.json

@@ -5,12 +5,6 @@
     "label": "micro-frontend",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "framework-plugin",
-    "label": "framework-plugin",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "model",

package/docs/en/guides/topic-detail/generator/create/config.mdx

@@ -40,16 +40,6 @@ import PackageManager from '@site-docs-en/components/package-manager';
 
 <PackageManager />
 
-### buildTools
-
-Question: Please select the bundler.
-
-Options:
-
-- webpack -- webpack
-
-- Rspack -- rspack
-
 ## Npm Module
 
 ### packageName

package/docs/en/guides/topic-detail/generator/create/use.mdx

@@ -35,7 +35,6 @@ npx @modern-js/create@latest web-app
 ? 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
 ```
 
 ### Create an Npm Module Project

package/docs/en/plugin/_meta.json

@@ -0,0 +1,19 @@
+[
+  "introduction",
+  {
+    "type": "dir",
+    "name": "plugin-system",
+    "label": "plugin-system",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "cli-plugins",
+    "label": "cli-plugins"
+  },
+  {
+    "type": "dir",
+    "name": "rsbuild-plugins",
+    "label": "rsbuild-plugins"
+  }
+]

package/docs/en/plugin/cli-plugins/_meta.json

@@ -0,0 +1 @@
+["plugin-tailwind", "plugin-bff", "plugin-ssg", "plugin-swc"]

package/docs/en/plugin/cli-plugins/plugin-bff.mdx

@@ -0,0 +1,5 @@
+# BFF Plugin
+
+In a Modern.js application, developers can define API files under the `api/lambda` directory and export API functions using the BFF plugin. In the frontend code, these API functions can be directly invoked by importing the file, which initiates the API requests.
+
+For more details, refer to [BFF - Basic Usage](/guides/advanced-features/bff/function).

package/docs/en/plugin/cli-plugins/plugin-ssg.mdx

@@ -0,0 +1,5 @@
+# SSG Plugin
+
+SSG (Static Site Generation) is a technical solution that renders complete static web pages at build time based on data and templates. This means that in a production environment, pages are populated with content by default and can be cached by a CDN. For pages that do not require dynamic data, SSG can provide better performance and higher security.
+
+For more details, refer to [Static Site Generation (SSG)](/guides/basic-features/render/ssg).

package/docs/en/{guides/rsbuild-plugins → plugin/cli-plugins}/plugin-swc.mdx

@@ -4,6 +4,13 @@ sidebar_position: 2
 
 # SWC Plugin
 
+:::warning
+**The SWC feature in the current document is no longer maintained**, we recommend using the Rspack + SWC solution.
+
+Please refer to [「Use Rspack」](guides/advanced-features/rspack-start) for more information.
+
+:::
+
 import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
 
 <SWC />

package/docs/en/plugin/cli-plugins/plugin-tailwind.mdx

@@ -0,0 +1,5 @@
+# Tailwind CSS Plugin
+
+Tailwind CSS is a utility-first CSS framework and design system that allows you to quickly add commonly used styles to components while supporting flexible theme style extensions.
+
+For more details, refer to [Using Tailwind CSS](/guides/basic-features/css/tailwindcss).

package/docs/en/plugin/cli-plugins.mdx

@@ -0,0 +1,6 @@
+# Overview
+
+- [@modern-js/plugin-tailwindcss](/plugin/cli-plugins/plugin-tailwind): Enables the use of Tailwind CSS styles.
+- [@modern-js/plugin-bff](/plugin/cli-plugins/plugin-bff): Provides BFF services and unified invocation capabilities.
+- [@modern-js/plugin-ssg](/plugin/cli-plugins/plugin-ssg): Provides static site generation capabilities.
+- [@modern-js/plugin-swc](/plugin/cli-plugins/plugin-swc): Provides SWC compilation support.