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

package/docs/zh/configure/app/tools/minify-css.mdx

@@ -0,0 +1,57 @@
+---
+title: minifyCss
+---
+
+# tools.minifyCss
+
+- **类型：** `Object | Function | undefined`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  minimizerOptions: {
+    preset: [
+      'default',
+      {
+        mergeLonghand: false,
+      },
+    ],
+  },
+};
+```
+
+在生产环境构建时，Modern.js 会通过 [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) 对 CSS 代码进行压缩优化。可以通过 `tools.minifyCss` 修改 [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) 的配置。
+
+### Object 类型
+
+当 `tools.minifyCss` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 合并。
+
+例如下面修改 [cssnano](https://cssnano.co/) 的 `preset` 配置：
+
+```js
+export default {
+  tools: {
+    minifyCss: {
+      minimizerOptions: {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.minifyCss` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
+
+```js
+export default {
+   tools: {
+    minifyCss: options => {
+      options.minimizerOptions = {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    }
+  }
+};
+```

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

@@ -0,0 +1,39 @@
+---
+title: postcss
+---
+
+# tools.postcss
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  postcssOptions: {
+    plugins: [
+      // 以下插件默认启用
+      require('postcss-nesting'),
+      require('postcss-media-minmax'),
+      require('postcss-flexbugs-fixes'),
+      require('autoprefixer')({
+        flexbox: 'no-2009',
+      }),
+      // 以下插件仅在需要兼容低版本浏览器时启用
+      require('postcss-custom-properties'),
+      require('postcss-initial'),
+      require('postcss-page-break'),
+      require('postcss-font-variant'),
+    ],
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
+  },
+};
+```
+
+Modern.js 默认集成 PostCSS，你可以通过 `tools.postcss` 对 [postcss-loader](https://github.com/webpack-contrib/postcss-loader) 进行配置。
+
+需要注意的是，当你开启 `tools.lightningcss` 配置时，PostCSS 将会被默认禁用，包括 `postcss-loader` 及其默认插件。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.postcss" />

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

@@ -0,0 +1,14 @@
+---
+title: rspack
+---
+
+# tools.rspack
+
+- **类型：** `Rspack.Configuration | Function | undefined`
+- **默认值：** `undefined`
+
+`tools.rspack` 选项用于修改 [Rspack](https://rspack.rs/) 的配置项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.rspack" />

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

@@ -0,0 +1,80 @@
+---
+title: sass
+---
+
+# tools.sass
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  // 默认在开发环境下启用 CSS 的 Source Map
+  sourceMap: isDev,
+};
+```
+
+你可以通过 `tools.sass` 修改 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置。
+
+### Object 类型
+
+当 `tools.sass` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.sass` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    sass(config) {
+      // 修改 sourceMap 配置
+      config.additionalData = async (content, loaderContext) => {
+        // ...
+      };
+    },
+  },
+};
+```
+
+### 修改 Sass 版本
+
+在某些场景下，如果你需要使用特定的 Sass 版本，而不是使用 Modern.js 内置的 Dart Sass v1，可以在项目中安装需要使用的 Sass 版本，并通过 `sass-loader` 的 `implementation` 选项设置。
+
+```js
+export default {
+  tools: {
+    sass: {
+      implementation: require('sass'),
+    },
+  },
+};
+```
+
+### 工具函数
+
+#### addExcludes
+
+- **类型：** `(excludes: RegExp | RegExp[]) => void`
+
+用来指定 `sass-loader` 不编译哪些文件，你可以传入一个或多个正则表达式来匹配 sass 文件的路径。例如：
+
+```js
+export default {
+  tools: {
+    sass(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/zh/configure/app/tools/style-loader.mdx

@@ -0,0 +1,14 @@
+---
+title: styleLoader
+---
+
+# tools.styleLoader
+
+- **类型：** `Object | Function`
+- **默认值：** `{}`
+
+通过 `tools.styleLoader` 可以设置 [style-loader](https://github.com/webpack-contrib/style-loader) 的配置项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.styleLoader" />

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

@@ -0,0 +1,69 @@
+---
+title: swc
+---
+
+# tools.swc
+
+- **类型：** `Object | Function`
+- **默认值：** `undefined`
+
+## 介绍
+
+import SWC from '@site-docs/components/swc.mdx';
+
+<SWC />
+
+:::tip
+在使用 Rspack 作为打包工具时，默认会使用 SWC 进行转译和压缩，因此你不需要再安装和配置 SWC 插件。
+:::
+
+## 在 Rspack 模式下使用
+
+通过 `tools.swc` 可以设置 Rspack [builtin:swc-loader](https://rspack.rs/zh/guide/features/builtin-swc-loader) 的选项。
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsc: {
+        externalHelpers: false,
+      },
+    },
+  },
+});
+```
+
+更多用法可参考 [Rsbuild - tools.swc](https://v2.rsbuild.rs/zh/config/tools/swc)。
+
+### 注册 SWC 插件
+
+Modern.js 支持通过 `tools.swc` 注册 SWC 的 Wasm 插件，比如注册 [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components)：
+
+```ts
+export default {
+  tools: {
+    swc: {
+      jsc: {
+        experimental: {
+          plugins: [['@swc/plugin-styled-components', {}]],
+        },
+      },
+    },
+  },
+};
+```
+
+需要注意的是，SWC 的插件仍然是一个实验性功能，目前 SWC 的 Wasm 插件是不向后兼容的，SWC 插件的版本与 Rspack 依赖的 swc_core 版本存在强耦合关系。
+
+这意味着，你需要选择和当前 swc_core 版本匹配的 SWC 插件，才能使它正常执行。如果你使用的 SWC 插件版本与 Rspack 依赖的 swc_core 版本不匹配，Rspack 在执行构建时会抛出如下错误：
+
+```
+1: failed to run Wasm plugin transform. Please ensure the version of `swc_core`
+   used by the plugin is compatible with the host runtime.
+```
+
+如果你遇到了以上问题，通常可行的解决方法是将 Modern.js 和 SWC 插件都升级到最新版本。
+
+详情可参考 [Rsbuild - SWC 插件版本](https://v2.rsbuild.rs/zh/guide/configuration/swc#swc-%E6%8F%92%E4%BB%B6%E7%89%88%E6%9C%AC)。

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -0,0 +1,56 @@
+---
+title: tsChecker
+---
+
+# tools.tsChecker
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  typescript: {
+    // avoid OOM issue
+    memoryLimit: 8192,
+    // use tsconfig of user project
+    configFile: tsconfigPath,
+    // use TS-Go native preview of user project
+    typescriptPath: require.resolve('@typescript/native-preview/package.json'),
+  },
+  issue: {
+    exclude: [
+      { file: '**/*.(spec|test).ts' },
+      { file: '**/node_modules/**/*' },
+    ],
+  },
+  logger: {
+    log() {
+      // do nothing
+      // we only want to display error messages
+    },
+    error(message: string) {
+      console.error(message.replace(/ERROR/g, 'Type Error'));
+    },
+  },
+},
+```
+
+默认情况下，Modern.js 会开启 [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check) 进行类型检查。你可以通过 `output.disableTsChecker` 配置项来关闭类型检查。
+
+## 示例
+
+当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        exclude: [({ file = '' }) => /[\\/]some-folder[\\/]/.test(file)],
+      },
+    },
+  },
+};
+```
+
+> 请参考 [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check) 了解更多用法。

package/docs/zh/configure/app/usage.mdx

@@ -0,0 +1,276 @@
+# 配置使用
+
+Modern.js 中有三种配置，分别是编译时配置、运行时配置和服务端运行时配置。
+
+**编译时配置**可以在两个位置进行配置：
+
+- 根路径下的 `modern.config.(ts|js|mjs)` 文件
+- `package.json` 文件
+
+:::info
+Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置同一个配置项，推荐在 `modern.config.ts` 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
+:::
+
+**运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
+
+**服务端运行时配置**可以在 `server/modern.server.(ts|js|mjs)` 中进行配置。
+
+## 编译时配置
+
+### 在配置文件中配置
+
+Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js` 和 `.mjs` 格式：
+
+- `modern.config.ts`
+- `modern.config.js`
+- `modern.config.mjs`
+
+#### modern.config.ts（推荐）
+
+我们推荐使用 `.ts` 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
+
+从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+#### modern.config.js
+
+如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
+
+```js title="modern.config.js"
+export default {
+  source: {
+    alias: opts => {
+      opts['@common'] = './src/common';
+    },
+  },
+};
+```
+
+你也可以通过 `process.env.NODE_ENV`，根据环境做不同配置：
+
+```js title="modern.config.js"
+export default {
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+#### 导出配置函数
+
+Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(({ env, command }) => ({
+  source: {
+    alias: {
+      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
+    },
+  },
+}));
+```
+
+该函数接受以下入参：
+
+- `env`：对应 `process.env.NODE_ENV` 的值。
+  - 当运行 `modern dev` 时，`env` 的值为 `development`。
+  - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
+- `command`：对应当前运行的命令，如 `dev`、`build`、`serve`。
+
+#### 导出异步函数
+
+Modern.js 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(async ({ env, command }) => {
+  const result = await someAsyncFunction();
+
+  return {
+    html: {
+      title: result,
+    },
+  };
+});
+```
+
+#### 指定配置文件
+
+Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称。
+
+例如，你需要在执行 `build` 命令时使用 `modern.prod.config.ts` 文件，可以在 `package.json` 中添加如下配置：
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "modern modern",
+    "build": "modern build --config modern.prod.config.ts"
+  }
+}
+```
+
+你也可以将 `--config` 选项缩写为 `-c`：
+
+```bash
+$ modern build -c modern.prod.config.js
+```
+
+### 在 package.json 中配置（不推荐）
+
+除了配置文件外，你也可以在 `package.json` 中的 `modernConfig` 字段下设置配置项，如：
+
+```json title="package.json"
+{
+  "modernConfig": {
+    "source": {
+      "alias": {
+        "@common": "./src/common"
+      }
+    }
+  }
+}
+```
+
+由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
+
+#### 注意事项
+
+- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
+
+### 本地调试配置
+
+为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
+
+#### 示例
+
+比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+如果你在本地调试时需要将端口号修改为 `3001`，但是又不希望修改当前项目的 `modern.config.ts` 文件，那么可以创建一个 `modern.config.local.ts` 文件，并添加以下配置：
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+`modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
+
+#### 注意事项
+
+在使用 `modern.config.local.ts` 时，请注意以下事项：
+
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
+- 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
+
+```bash title=".gitignore"
+modern.config.local.*
+```
+
+### 合并多份配置
+
+在某些情况下，你可能需要将多份配置合并为一份配置，此时你可以使用 `mergeConfig` 工具函数来合并多个配置。
+
+`mergeConfig` 函数接受一个数组作为参数，数组中的每一项都是一个配置对象，`mergeConfig` 会将数组中的每一项配置对象进行深层合并，自动将多个函数项合并为数组，最终返回一个合并后的配置对象。
+
+#### 示例
+
+```ts title="modern.config.ts"
+import { mergeConfig } from '@modern-js/app-tools';
+
+const config1 = {
+  dev: {
+    port: 3000,
+  },
+  tools: {
+    postcss: () => console.log('config1');
+  },
+};
+const config2 = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: () => console.log('config2');
+  },
+};
+
+const mergedConfig = mergeConfig([config1, config2]);
+```
+
+在以上示例中，合并后的配置对象为：
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```
+
+### 配置类型定义
+
+Modern.js 导出了 `AppUserConfig` 类型，对应 Modern.js 配置对象的类型：
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig = {
+  tools: {
+    rspack: {},
+  },
+};
+```
+
+## 运行时配置
+
+运行时配置的详细信息可以参考 [Runtime 配置介绍](/configure/app/runtime/0-intro.html)。
+
+:::tip
+如果当前的 Runtime 配置需要在编译时和运行时同时使用，请将相关配置参数添加到插件注册的位置。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { xxPlugin } from '@modern-js/plugin-xx';
+
+export default defineConfig({
+  plugins: [
+    xxPlugin({
+      /** 在此处添加参数 */
+    }),
+  ],
+});
+```
+
+:::

package/docs/zh/guides/_meta.json

@@ -0,0 +1,37 @@
+[
+  {
+    "type": "dir",
+    "name": "get-started",
+    "label": "gettingStarted"
+  },
+  {
+    "type": "dir",
+    "name": "concept",
+    "label": "concept"
+  },
+  {
+    "type": "dir",
+    "name": "basic-features",
+    "label": "basic"
+  },
+  {
+    "type": "dir",
+    "name": "advanced-features",
+    "label": "advanced"
+  },
+  {
+    "type": "dir",
+    "name": "topic-detail",
+    "label": "topic"
+  },
+  {
+    "type": "dir",
+    "name": "troubleshooting",
+    "label": "troubleshooting"
+  },
+  {
+    "type": "dir",
+    "name": "upgrade",
+    "label": "从 Modern.js 2.0 升级"
+  }
+]

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

@@ -0,0 +1,32 @@
+[
+  {
+    "type": "dir",
+    "name": "bff",
+    "label": "use-bff",
+    "collapsed": true
+  },
+
+  {
+    "type": "dir",
+    "name": "page-performance",
+    "label": "page-performance",
+    "collapsed": true
+  },
+  "build-performance",
+  "compatibility",
+  "low-level",
+  "source-build",
+  {
+    "type": "dir",
+    "name": "server-monitor",
+    "label": "server-monitor",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "international",
+    "label": "国际化",
+    "collapsed": true
+  },
+  "web-server"
+]

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

@@ -0,0 +1,10 @@
+[
+  "function",
+  "frameworks",
+  "data-platform",
+  "operators",
+  "extend-server",
+  "sdk",
+  "upload",
+  "cross-project"
+]