@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,49 @@
+[
+  {
+    "type": "dir",
+    "name": "routes",
+    "label": "路由",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "data",
+    "label": "data-solution",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "render",
+    "label": "rendering",
+    "collapsed": true
+  },
+  {
+    "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",
+  "env-vars",
+  "output-files",
+  "deploy"
+]

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

@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+---
+
+# 路径别名
+
+路径别名（alias）允许开发者为模块定义别名，以便于在代码中更方便的引用它们。当你想要使用一个简短、易于记忆的名称来代替冗长复杂的路径时，这将非常有用。
+
+例如，假如你在项目中经常引用 `src/common/request.ts` 模块，你可以为它定义一个别名 `@request`，然后在代码中通过 `import request from '@request'` 来引用它，而不需要每次都写出完整的相对路径。同时，这也允许你将模块移动到不同的位置，而不需要更新代码中的所有 import 语法。
+
+在 Modern.js 中，你有两种方式可以设置路径别名:
+
+- 通过 `tsconfig.json` 中的 `paths` 配置。
+- 通过 [source.alias](/configure/app/source/alias) 配置。
+
+## 通过 `tsconfig.json` 的 `paths` 配置
+
+你可以通过 `tsconfig.json` 中的 `paths` 来配置别名，这是我们在 TypeScript 项目中推荐使用的方式，因为它可以解决路径别名的 TS 类型问题。比如：
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "@common/*": ["./src/common/*"]
+    }
+  }
+}
+```
+
+以上配置完成后，如果你在代码中引用 `@common/Foo.tsx`，则会映射到 `<project>/src/common/Foo.tsx` 路径上。
+
+:::tip
+你可以阅读 [TypeScript - paths](https://www.typescriptlang.org/tsconfig#paths) 文档来了解更多用法。
+:::
+
+## 通过 `source.alias` 配置
+
+Modern.js 提供了 [source.alias](/configure/app/source/alias) 配置项，你可以通过对象或者函数的方式来配置这个选项。
+
+### 使用场景
+
+由于 `tsconfig.json` 的 `paths` 配置是写在静态 JSON 文件里的，因此它不具备动态性。
+
+而 `source.alias` 则可以弥补这一不足，你可以通过 JavaScript 代码来动态设置 `source.alias`（比如基于环境变量来设置）。
+
+### 对象用法
+
+你可以通过对象的方式来配置 `source.alias`，其中的相对路径会被自动补全为绝对路径。比如：
+
+```js
+export default {
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+};
+```
+
+以上配置完成后，如果你在代码中引用 `@common/Foo.tsx`，则会映射到 `<project>/src/common/Foo.tsx` 路径上。
+
+### 函数用法
+
+你也可以将 `source.alias` 配置为一个函数，拿到内置的 `alias` 对象，对其进行修改。比如：
+
+```js
+export default {
+  source: {
+    alias: alias => {
+      alias['@common'] = './src/common';
+      return alias;
+    },
+  },
+};
+```
+
+### 优先级
+
+`tsconfig.json` 的 `paths` 配置的优先级高于 `source.alias`，当一个路径同时匹配到这两者定义的规则时，会优先使用 `tsconfig.json` 的 `paths` 定义的值。
+
+你可以通过 [source.aliasStrategy](/configure/app/source/alias-strategy) 来调整这两个选项的优先级。
+
+## 默认别名
+
+Modern.js 框架内置了以下别名:
+
+```json
+{
+  "@": "./src",
+  "@shared": "./shared"
+}
+```
+
+此外，在启用框架的 BFF 插件时，默认会添加 `@api` 别名。
+
+```json
+{
+  "@api": "./api"
+}
+```

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,69 @@
+# 使用 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 插件 `@modern-js/plugin-styled-components` 提供了对 styled-components 的支持，并为 styled-components 添加了服务器端渲染能力。你可以通过安装 `@modern-js/plugin-styled-components` 插件来使用 styled-components。
+
+## 在 Modern.js 中使用 styled-components
+
+首先，你需要安装 `styled-components` 插件依赖和 `styled-components` 库：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components styled-components -D',
+    pnpm: 'pnpm install @modern-js/plugin-styled-components styled-components -D',
+  }}
+/>
+
+然后在 `modern.config.ts` 中配置 `styled-components` 插件：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
+
+export default defineConfig({
+  plugins: [
+    styledComponentsPlugin({
+      // ...
+      displayName: true,
+      minify: process.env.NODE_ENV === 'production',
+    }),
+  ],
+});
+```
+
+styledComponentsPlugin 插件的配置项与 [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) 插件的配置项相同，你可以参考 [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) 插件的文档进行配置。
+
+## 使用 styled-components 编写样式
+
+当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
+
+```js
+import styled from '@modern-js/plugin-styled-components/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
+
+```js
+import styled from '@modern-js/plugin-styled-components/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
+
+:::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-modules.mdx

@@ -0,0 +1,218 @@
+---
+sidebar_position: 14
+---
+
+# 使用 CSS Modules
+
+[CSS Modules](https://github.com/css-modules/css-modules) 让我们能以模块化的方式编写 CSS 代码，并且可以在 JavaScript 文件中导入和使用这些样式。使用 CSS Modules 可以自动生成唯一的类名，隔离不同模块之间的样式，避免类名冲突。
+
+Modern.js 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 `[name].module.css` 文件名来启用 CSS Modules。
+
+以下样式文件会被视为 CSS Modules：
+
+- `*.module.scss`
+- `*.module.less`
+- `*.module.css`
+
+## 示例
+
+- 编写样式：
+
+```css
+/* button.module.css */
+.error {
+  background: red;
+}
+```
+
+- 使用样式：
+
+```tsx
+// Button.tsx
+import React, { Component } from 'react';
+// 引入样式文件
+import styles from './button.module.css';
+
+export default () => {
+  return <button className={styles.error}>Error Button</button>;
+};
+```
+
+## 为所有样式文件启用 CSS Modules
+
+在默认情况下，只有 `*.module.css` 结尾的文件才被视为 CSS Modules 模块。
+
+如果你想将源码目录下的所有 CSS 文件当做 CSS Modules 模块进行处理，可以通过开启 [output.disableCssModuleExtension](/configure/app/output/disable-css-module-extension) 来实现，比如：
+
+```ts
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+设置后，以下两个文件都会被视为 CSS Modules：
+
+```ts
+import styles1 from './foo.module.css';
+import styles2 from './bar.css';
+```
+
+:::tip
+我们不推荐开启此配置项，因为开启 `disableCssModuleExtension` 后，CSS Modules 文件和普通 CSS 文件无法得到明确的区分，不利于长期维护。
+:::
+
+## 为指定的样式文件启用 CSS Modules
+
+在默认情况下，只有 `*.module.css` 结尾的文件才被视为 CSS Modules 模块。
+
+如果你想只为一些指定的样式文件启用 CSS Modules，可以通过配置 [output.cssModules](/configure/app/output/css-modules) 来实现，比如：
+
+```ts
+export default {
+  output: {
+    cssModules: {
+      auto: resource => {
+        return resource.includes('.module.') || resource.includes('shared/');
+      },
+    },
+  },
+};
+```
+
+如果你需要自定义 CSS Modules 的其他配置，可以通过 [tools.cssLoader](/configure/app/tools/css-loader) 进行设置。
+
+## 添加类型声明
+
+当你在 TypeScript 代码中引用 CSS Modules 时，TypeScript 可能会提示该模块缺少类型定义：
+
+```
+TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
+```
+
+此时你需要为 CSS Modules 添加类型声明文件，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明：
+
+```ts title="src/global.d.ts"
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+如果你开启了 `disableCssModuleExtension` 配置值，还需要添加以下类型：
+
+```ts title="src/global.d.ts"
+declare module '*.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `global.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
+
+## 生成准确的类型定义
+
+上述方法虽然可以解决 CSS Modules 在 TypeScript 中的类型问题，但是无法准确地提示出某个 CSS 文件导出了哪些类名。
+
+Modern.js 支持为 CSS Modules 生成准确的类型声明，你只需要开启 [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration) 配置项，再执行构建命令，Modern.js 就会为项目中所有的 CSS Modules 文件生成相应的类型声明文件。
+
+```ts
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+### 示例
+
+例如某个文件夹下面有 `src/index.ts` 和 `src/index.module.scss` 两个文件：
+
+```tsx title="src/index.ts"
+import styles from './index.module.scss';
+
+export default () => {
+  return (
+    <div>
+      <div className={styles.pageHeader}>Page Header</div>
+    </div>
+  );
+};
+```
+
+```scss title="src/index.module.scss"
+.page-header {
+  color: black;
+}
+```
+
+执行构建命令后，会自动生成 `src/index.module.scss.d.ts` 类型声明文件：
+
+```ts title="src/index.module.scss.d.ts"
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'page-header': string;
+  pageHeader: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```
+
+此时再打开 `src/index.ts` 文件，可以看到 `styles` 对象已经具备了准确的类型。
+
+### 相关配置
+
+在上述例子中，`src/index.module.scss.d.ts` 是编译生成的代码，你可以选择将它们提交到 Git 仓库里，也可以选择在 `.gitignore` 文件中忽略它们：
+
+```bash
+# Ignore auto generated CSS declarations
+*.module.css.d.ts
+*.module.sass.d.ts
+*.module.scss.d.ts
+*.module.less.d.ts
+*.module.styl.d.ts
+```
+
+此外，如果生成的代码导致了 ESLint 报错，你也可以将上述配置添加到 `.eslintignore` 文件里。

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

@@ -0,0 +1,31 @@
+---
+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://v2.rsbuild.rs/zh/plugins/list/plugin-stylus)。
+
+## 使用 PostCSS
+
+Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
+
+请阅读 [Rsbuild - 使用 PostCSS](https://v2.rsbuild.rs/zh/guide/styling/css-usage) 了解更多用法。
+
+## 使用 Lightning CSS
+
+Modern.js 支持使用 [Lightning CSS](https://lightningcss.dev/) 来转换 CSS 代码，可以通过配置 [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) 来开启此功能。
+
+请阅读 [Rsbuild - 使用 Lightning CSS](https://v2.rsbuild.rs/zh/guide/styling/css-usage#lightning-css) 了解更多用法。
+
+## 使用 Uno CSS
+
+请阅读 [Rsbuild - 使用 UnoCSS](https://v2.rsbuild.rs/zh/guide/styling/unocss) 了解更多用法。

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

@@ -0,0 +1,27 @@
+# 使用 Tailwind CSS
+
+[Tailwind CSS](https://tailwindcss.com/) 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。
+
+## 在 Modern.js 中使用 Tailwind CSS
+
+在 Modern.js 中使用 [Tailwind CSS](https://tailwindcss.com/)，你只需要按照 Rsbuild 操作步骤进行配置，Rsbuild 支持 Tailwind CSS v3 和 v4 版本：
+
+- [Tailwind CSS v3](https://v2.rsbuild.rs/zh/guide/styling/tailwindcss-v3#tailwind-css-v3)
+- [Tailwind CSS v4](https://v2.rsbuild.rs/zh/guide/styling/tailwindcss)
+
+## Tailwind CSS 自动补全
+
+Tailwind CSS 官方提供了 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件，用于在 VS Code 中自动补全 Tailwind CSS 的 class names、CSS functions 和 directives。
+
+你可以参考以下步骤来启动自动补全功能：
+
+1. 在 VS Code 中安装 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件。
+2. 如果项目的根目录没有 `tailwind.config.{ts,js}` 文件，那么你需要创建该文件，并写入当前项目的 Tailwind CSS 配置，否则 IDE 插件将无法正确生效。
+
+## 浏览器兼容性
+
+Tailwind CSS v3 不支持 IE 11 浏览器，相关背景请参考：
+
+- [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support)。
+
+如果你在 IE 11 浏览器上使用 Tailwind CSS，可能会出现部分样式不可用的现象，请谨慎使用。

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

@@ -0,0 +1 @@
+["data-fetch", "data-write", "data-cache"]