@modern-js/main-doc 0.0.0-nightly-20240902170725 → 0.0.0-nightly-20240904170727

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/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/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/tutorials/first-app/c03-css.mdx

@@ -294,7 +294,7 @@ A Utility Class named `custom-text-gray` is implemented in `src/routes/styles/ut
 ```
 
 :::info note
-Modern.js integrates with [PostCSS](/guides/basic-features/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+Modern.js integrates with [PostCSS](/guides/basic-features/css/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
 
 :::
 

package/docs/zh/components/init-app.mdx

@@ -4,7 +4,6 @@
 ? 请选择你想创建的工程类型 Web 应用
 ? 请选择开发语言 TS
 ? 请选择包管理工具 pnpm
-? 请选择构建工具 webpack
 ```
 
 在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。

package/docs/zh/components/init-rspack-app.mdx

@@ -3,5 +3,4 @@ $ npx @modern-js/create@latest myapp
 ? 请选择你想创建的工程类型：Web 应用
 ? 请选择开发语言：TS
 ? 请选择包管理工具：pnpm
-? 请选择构建工具：Rspack
 ```

package/docs/zh/configure/app/tools/tailwindcss.mdx

@@ -23,7 +23,7 @@ const tailwind = {
 
 在使用 `tools.tailwindcss` 之前，你需要启用 Modern.js 的 Tailwind CSS 插件。
 
-请阅读[「使用 Tailwind CSS」](/guides/basic-features/css.html#使用-tailwind-css) 章节来了解开启方式。
+请阅读[「使用 Tailwind CSS」](/guides/basic-features/css/tailwindcss) 章节来了解开启方式。
 
 ### Function 类型
 

package/docs/zh/guides/advanced-features/_meta.json

@@ -14,6 +14,5 @@
   "build-performance",
   "inline-assets",
   "optimize-bundle",
-  "using-storybook",
   "web-server"
 ]

package/docs/zh/guides/advanced-features/rsbuild-plugin.mdx

@@ -41,8 +41,8 @@ Modern.js 从 `MAJOR_VERSION.46.0` 起开始将底层的构建工具升级为 [R
 | [CSS Minimizer 插件](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer)         | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩。 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
 | [Pug 插件](https://github.com/rspack-contrib/rsbuild-plugin-pug)                             | 提供对 Pug 模板引擎的支持                                                                | [tools.pug](/configure/app/tools/pug.html)                                                                                            |
 | [Rem 插件](https://github.com/rspack-contrib/rsbuild-plugin-rem)                             | 用于实现移动端页面的 rem 自适应布局                                                      | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
-| [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | 用于引用 YAML 文件，并将其转换为 JavaScript 对象                                         | [TOML 文件](/guides/basic-features/json-files.html#toml-文件)                                                                         |
-| [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | 用于引用 TOML 文件，并将其转换为 JavaScript 对象                                         | [YAML 文件](/guides/basic-features/json-files.html#yaml-文件)                                                                         |
+| [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | 用于引用 YAML 文件，并将其转换为 JavaScript 对象                                         | [TOML 文件](/guides/basic-features/static-assets/json-files.html#toml-文件)                                                                         |
+| [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | 用于引用 TOML 文件，并将其转换为 JavaScript 对象                                         | [YAML 文件](/guides/basic-features/static-assets/json-files.html#yaml-文件)                                                                         |
 
 ### 未内置插件
 

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -8,13 +8,13 @@ import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspackTip.mdx';
 
 <Rspack />
 
-**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。
+**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 webpack 和更快的 Rspack 之间进行切换。
 
 这篇文档会向你介绍如何在 Modern.js 中开启 Rspack 构建模式。
 
 ## 初始化 Rspack 项目
 
-Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 **Rspack**，即可创建一个 Rspack 项目:
+Modern.js 新项目已默认启用 Rspack 构建，只需执行 [初始化项目](/guides/get-started/quick-start.html#初始化项目)，即可创建一个 Rspack 项目:
 
 import InitRspackApp from '@site-docs/components/init-rspack-app';
 
@@ -24,7 +24,7 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 
 ## 开启 Rspack 构建
 
-从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
+从 Modern.js MAJOR_VERSION.59.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
 
 ```diff title=modern.config.ts
 import { appTools, defineConfig } from '@modern-js/app-tools';
@@ -32,14 +32,14 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   plugins: [
     appTools({
-+     bundler: 'experimental-rspack',
++     bundler: 'rspack',
     }),
   ],
 });
 ```
 
 :::tip
-如果你当前版本低于 MAJOR_VERSION.46.0, 可通过执行 `npx modern upgrade` 进行升级。
+如果你当前版本低于 MAJOR_VERSION.59.0, 可通过执行 `npx modern upgrade` 进行升级。
 :::
 
 import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
@@ -70,13 +70,6 @@ export default {
 };
 ```
 
-
-:::tip
-开启 Rspack 构建能力后，目前有小部分配置在 Rspack 中还不支持使用，如 [source.moduleScopes](/configure/app/source/module-scopes)、[security.sri](/configure/app/security/sri) 等。
-
-对于不支持的配置，我们在文档中有标注 `打包工具： 仅支持 webpack` 或 `打包工具： 仅支持 rspack`，可参考具体配置介绍。
-:::
-
 ## 修改转译配置
 
 Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 进行代码转译。
@@ -105,7 +98,7 @@ export default defineConfig<'rspack'>({
 
 通常情况下，Modern.js 内会集成 Rspack 的最新版本，通过 `npx modern upgrade` 即可将当前项目中的 Modern.js 相关依赖以及内置的 Rspack 更新至最新版本。
 
-但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
+但 Modern.js 对于 Rspack 的依赖方式为锁版本方式（非自动升级），由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
 
 当你执行 dev / build 命令时，Modern.js 会在[开启调试模式时](https://rsbuild.dev/zh/guide/debug/debug-mode)自动打印当前使用的 Rspack 版本：
 
@@ -140,9 +133,7 @@ export default defineConfig<'rspack'>({
       "@rspack/plugin-react-refresh": "npm:@rspack/plugin-react-refresh@nightly"
     },
     "peerDependencyRules": {
-      "allowAny": [
-        "@rspack/*"
-      ]
+      "allowAny": ["@rspack/*"]
     }
   }
 }

package/docs/zh/guides/basic-features/_meta.json

@@ -12,17 +12,33 @@
     "label": "rendering",
     "collapsed": true
   },
-  "css",
+  {
+    "type": "dir",
+    "name": "css",
+    "label": "css-solution",
+    "collapsed": true
+  },
+  "html",
+  {
+    "type": "dir",
+    "name": "static-assets",
+    "label": "static-assets",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "debug",
+    "label": "debug",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "testing",
+    "label": "testing",
+    "collapsed": true
+  },
   "alias",
-  "mock",
-  "proxy",
   "env-vars",
-  "html",
   "output-files",
-  "static-assets",
-  "svg-assets",
-  "json-files",
-  "wasm-assets",
-  "css-modules",
   "deploy"
 ]

package/docs/zh/guides/basic-features/css/_meta.json

@@ -0,0 +1 @@
+["css", "css-modules", "css-in-js", "tailwindcss"]

package/docs/zh/guides/basic-features/css/css-in-js.mdx

@@ -0,0 +1,34 @@
+# 使用 CSS-in-JS
+
+CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。
+
+Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
+
+当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
+
+Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 插件，你可以通过 [tools.styledComponents](/configure/app/tools/styled-components) 对插件进行配置。
+
+:::tip 提示
+如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
+:::

package/docs/zh/guides/basic-features/css/css.mdx

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+---
+
+# 引入 CSS
+
+Modern.js 内置多种常用的 CSS 开发方案，包括 Less / Sass / Stylus 预处理器、PostCSS、CSS Modules、CSS-in-JS 和 Tailwind CSS。
+
+## 使用 Less、Sass 和 Stylus
+
+Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
+
+默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
+
+你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)。
+
+## 使用 PostCSS
+
+Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
+
+请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.dev/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
+
+## 使用 Uno CSS
+
+请阅读 [Rsbuild - 使用 UnoCSS](https://rsbuild.dev/zh/guide/basic/unocss) 了解更多用法。