@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -1,224 +0,0 @@
----
-title: babel
----
-
-# tools.babel
-
-- **类型：** `Object | Function`
-- **默认值：** `undefined`
-
-通过 `tools.babel` 可以修改 [babel-loader](https://github.com/babel/babel-loader) 的配置项。
-
-### 使用场景
-
-请留意 `tools.babel` 在以下使用场景中的局限性：
-
-- Rspack 场景：在使用 Rspack 作为打包工具时，使用 `tools.babel` 配置项将会明显拖慢 Rspack 构建速度。因为 Rspack 默认使用的是 SWC 编译，配置 Babel 会导致代码需要被编译两次，产生了额外的编译开销。
-- webpack + SWC 场景：在使用 webpack 作为打包工具时，如果你使用了 SWC 插件进行代码编译，那么 `tools.babel` 选项将不会生效。
-
-### Function 类型
-
-当 `tools.babel` 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 `babel-loader` 配置。
-
-```js
-export default {
-  tools: {
-    babel(config) {
-      // 添加一个插件，比如配置某个组件库的按需引入
-      config.plugins.push([
-        'babel-plugin-import',
-        {
-          libraryName: 'xxx-components',
-          libraryDirectory: 'es',
-          style: true,
-        },
-      ]);
-    },
-  },
-};
-```
-
-`tools.babel` 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
-
-:::tip
-以上示例仅作为参考，通常来说，你不需要手动配置 `babel-plugin-import`，因为 Modern.js 已经提供了更通用的 `source.transformImport` 配置。
-:::
-
-### Object 类型
-
-当 `tools.babel` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 浅合并。
-
-:::caution
-`Object.assign` 是浅拷贝，会完全覆盖内置的 `presets` 或 `plugins` 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
-:::
-
-```js
-export default {
-  tools: {
-    babel: {
-      plugins: [
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ],
-    },
-  },
-};
-```
-
-### 工具函数
-
-`tools.babel` 为 Function 类型时，第二个参数可用的工具函数如下:
-
-#### addPlugins
-
-- **类型：** `(plugins: BabelPlugin[]) => void`
-
-添加若干个 Babel 插件。
-
-```js
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ]);
-    },
-  },
-};
-```
-
-#### addPresets
-
-- **类型：** `(presets: BabelPlugin[]) => void`
-
-添加若干个 Babel 预设配置 (大多数情况下不需要增加预设)。
-
-```js
-export default {
-  tools: {
-    babel(config, { addPresets }) {
-      addPresets(['@babel/preset-env']);
-    },
-  },
-};
-```
-
-#### removePlugins
-
-- **类型：** `(plugins: string | string[]) => void`
-
-移除 Babel 插件，传入需要移除的插件名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
-
-```js
-export default {
-  tools: {
-    babel(config, { removePlugins }) {
-      removePlugins('babel-plugin-import');
-    },
-  },
-};
-```
-
-#### removePresets
-
-- **类型：** `(presets: string | string[]) => void`
-
-移除 Babel 预设配置，传入需要移除的预设名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
-
-```js
-export default {
-  tools: {
-    babel(config, { removePresets }) {
-      removePresets('@babel/preset-env');
-    },
-  },
-};
-```
-
-#### modifyPresetEnvOptions
-
-- **类型：** `(options: PresetEnvOptions) => void`
-
-修改 [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: 'last 2 versions',
-      });
-    },
-  },
-};
-```
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: {
-          chrome: '58',
-          ie: '11',
-        },
-      });
-    },
-  },
-};
-```
-
-#### modifyPresetReactOptions
-
-- **类型：** `(options: PresetReactOptions) => void`
-
-修改 [@babel/preset-react](https://babeljs.io/docs/en/babel-preset-react) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetReactOptions }) {
-      modifyPresetReactOptions({
-        pragma: 'React.createElement',
-      });
-    },
-  },
-};
-```
-
-#### addIncludes
-
-已废弃，请使用 [source.include](https://modernjs.dev/configure/app/source/include.html) 代替，两者功能完全一致。
-
-#### addExcludes
-
-已废弃，请使用 [source.exclude](https://modernjs.dev/configure/app/source/exclude.html) 代替，两者功能完全一致。
-
-### 调试 Babel 配置
-
-当你通过 `tools.babel` 修改 `babel-loader` 配置后，可以在 [调试模式](https://rsbuild.rs/zh/guide/debug/debug-mode) 下查看最终生成的配置。
-
-首先通过 `DEBUG=builder` 参数开启调试模式：
-
-```bash
-# 调试开发环境
-DEBUG=builder pnpm dev
-
-# 调试生产环境
-DEBUG=builder pnpm build
-```
-
-然后打开生成的 `(webpack|rspack).config.web.js`，搜索 `babel-loader` 关键词，即可看到完整的 `babel-loader` 配置内容。

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

@@ -1,44 +0,0 @@
----
-title: esbuild
----
-
-# tools.esbuild
-
-- **类型：** `Object`
-- **默认值：** `undefined`
-
-:::warning
-**当前文档中的 esbuild 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案，因为 Rspack + SWC 具备更好的构建性能、功能丰富度和产物兼容性。
-
-请参考[「使用 Rspack」](/guides/advanced-features/rspack-start.html)了解更多。
-
-:::
-
-## 介绍
-
-import Esbuild from '@site-docs/components/esbuild.mdx';
-
-<Esbuild />
-
-## 配置项
-
-你可以通过 `tools.esbuild` 配置项来设置 esbuild 编译行为。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    esbuild: {
-      loader: {
-        target: 'chrome61',
-      },
-      minimize: {
-        target: 'chrome61',
-      },
-    },
-  },
-});
-```
-
-完整配置项请参考 [esbuild 插件配置](/plugin/official/rsbuild-plugins/plugin-esbuild#配置)。

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

@@ -1,54 +0,0 @@
----
-title: pug
----
-
-# tools.pug
-
-- **类型：** `true | Object | Function | undefined`
-- **默认值：** `false`
-
-配置 [Pug](https://pugjs.org/) 模板引擎。
-
-### Boolean 类型
-
-Modern.js 默认不启用 Pug 模板引擎，你可以将 `tools.pug` 设置为 `true` 来启用它。
-
-```ts
-export default {
-  tools: {
-    pug: true,
-  },
-};
-```
-
-启用后，你可以在 `html.template` 中指定使用 `index.pug` 作为模板文件。
-
-### Object 类型
-
-当 `tools.terser` 的值为 `Object` 类型时，可以配置 Pug 模板引擎的选项：
-
-```ts
-export default {
-  tools: {
-    pug: {
-      doctype: 'xml',
-    },
-  },
-};
-```
-
-详细参数请查看 [Pug API Reference](https://pugjs.org/api/reference.html#options)。
-
-### Function 类型
-
-当 `tools.pug` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
-
-```ts
-export default {
-  tools: {
-    pug(config) {
-      config.doctype = 'xml';
-    },
-  },
-};
-```

package/docs/zh/configure/app/tools/styled-components.mdx

@@ -1,54 +0,0 @@
----
-title: styledComponents
----
-
-# tools.styledComponents
-
-- **类型：** `Object | Function | false`
-- **默认值：**
-
-```js
-{
-  displayName: true,
-  // 在 SSR 构建中 isSSR 为 true
-  ssr: isSSR,
-  // 在生产环境构建时启用 `pure` 来优化包体积
-  pure: isProd,
-  transpileTemplateLiterals: true,
-}
-```
-
-对应 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 或使用 SWC 时 [@swc/plugin-styled-components](https://github.com/swc-project/plugins/tree/main/packages/styled-components) 的配置。 值为 `Object` 类型时，利用 Object.assign 函数与默认配置合并。比如:
-
-```js
-export default {
-  tools: {
-    styledComponents: {
-      pure: false,
-    },
-  },
-};
-```
-
-值为 `Function` 类型时，第一个参数为默认配置，第二个参数提供了一些可以直接调用的工具函数：
-
-```js
-export default {
-  tools: {
-    styledComponents(config) {
-      // 修改 pure 配置
-      config.pure = false;
-    },
-  },
-};
-```
-
-该特性默认启用，你可以配置 `tools.styledComponents` 为 `false` 来关闭该行为，关闭后可以提升编译性能：
-
-```js
-export default {
-  tools: {
-    styledComponents: false,
-  },
-};
-```

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

@@ -1,98 +0,0 @@
----
-title: tailwindcss
----
-
-# tools.tailwindcss
-
-- **类型：** `Object | Function`
-- **默认值：**
-
-```js
-const tailwind = {
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './config/html/**/*.{html,ejs,hbs}',
-    './storybook/**/*',
-  ],
-};
-```
-
-用于修改 [Tailwind CSS](https://tailwindcss.com/docs/configuration) 的配置项。
-
-### 启用 Tailwind CSS
-
-在使用 `tools.tailwindcss` 之前，你需要启用 Modern.js 的 Tailwind CSS 插件。
-
-请阅读[「使用 Tailwind CSS」](/guides/basic-features/css/tailwindcss) 章节来了解开启方式。
-
-### Function 类型
-
-当 `tools.tailwindcss` 为 Function 类型时，默认配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个值作为最终结果：
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    tailwindcss(config) {
-      config.content.push('./some-folder/**/*.{js,ts}');
-    },
-  },
-};
-```
-
-### Object 类型
-
-当 `tools.tailwindcss` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 浅合并。
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    tailwindcss: {
-      plugins: [
-        require('@tailwindcss/forms'),
-        require('@tailwindcss/aspect-ratio'),
-        require('@tailwindcss/typography'),
-      ],
-    },
-  },
-};
-```
-
-### 注意事项
-
-注意：
-
-- 如果你同时使用了 `tailwind.config.{ts,js}` 文件和 `tools.tailwindcss` 选项，那么 `tools.tailwindcss` 定义的配置会优先生效，并覆盖 `tailwind.config.{ts,js}` 中定义的内容。
-- 如果你同时使用了 `source.designSystem` 配置项，那么 Tailwind CSS 的 `theme` 配置将会被 `source.designSystem` 的值所覆盖。
-
-其他配置的使用方式与 Tailwind CSS 官方用法一致，请参考 [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration)。
-
-### 关于 source.designSystem
-
-`source.designSystem` 是 Modern.js 中废弃的配置项。
-
-从 Modern.js vMAJOR_VERSION.33.0 版本开始，你可以使用 Tailwind CSS 的 `theme` 配置项来代替 `source.designSystem`，不再需要将 `theme` 配置拆分并设置到 `designSystem` 上。
-
-- 旧版本用法：
-
-```ts title="modern.config.ts"
-const { theme, ...rest } = tailwindConfig;
-
-export default {
-  tools: {
-    tailwindcss: rest,
-  },
-  source: {
-    designSystem: theme,
-  },
-};
-```
-
-- 当前版本用法：
-
-```ts title="modern.config.ts"
-export default {
-  tools: {
-    tailwindcss: tailwindConfig,
-  },
-};
-```

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

@@ -1,58 +0,0 @@
----
-title: terser
----
-
-# tools.terser
-
-import { Badge } from '@theme';
-
-<Badge type="danger" >仅支持 Webpack</Badge>
-
-- **类型：** `Object | Function | undefined`
-- **默认值：**
-
-```js
-const defaultTerserOptions = {
-  terserOptions: {
-    mangle: {
-      safari10: true,
-    },
-  },
-};
-```
-
-在生产环境构建时，Modern.js 会通过 [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) 对 JavaScript 代码进行压缩优化。可以通过 `tools.terser` 修改 [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) 的配置。
-
-### Object 类型
-
-当 `tools.terser` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 合并。
-
-例如通过 `exclude` 排除部分文件的压缩：
-
-```js
-export default {
-  tools: {
-    terser: {
-      exclude: /\/excludes/,
-    },
-  },
-};
-```
-
-### Function 类型
-
-当 `tools.terser` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
-
-```js
-export default {
-  tools: {
-    terser: opts => {
-      opts.exclude = /\/excludes/;
-    },
-  },
-};
-```
-
-:::tip 禁用代码压缩
-如果你需要禁用代码压缩，可以使用 [output.minify](/configure/app/output/minify) 配置项。
-:::

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

@@ -1,76 +0,0 @@
----
-title: tsLoader
----
-
-# tools.tsLoader
-
-import { Badge } from '@theme';
-
-<Badge type="danger" >仅支持 Webpack</Badge>
-
-- **类型：** `Object | Function | undefined`
-- **默认值：** `undefined`
-
-:::warning 废弃提示
-
-不推荐在项目中使用 ts-loader，原因如下：
-
-- 启用 ts-loader 时将无法使用 [source.transformImport](/configure/app/source/transform-import) 和 [tools.styledComponents](/configure/app/tools/styled-components) 等由 Babel 和 SWC 提供支持的能力。
-- Rspack 不支持使用 ts-loader。
-
-:::
-
-项目中默认不开启 ts-loader，当 `tools.tsLoader` 不为 undefined 则表示开启 ts-loader，同时禁用 babel-loader 对 TypeScript 的编译。
-
-### Object 类型
-
-当此值为 Object 类型时，与默认配置通过 Object.assign 合并。
-
-默认配置如下:
-
-```json
-{
-  "compilerOptions": {
-    "target": "es5",
-    "module": "ESNext"
-  },
-  "transpileOnly": true,
-  "allowTsInNodeModules": true
-}
-```
-
-你可以通过 `tools.tsLoader` 配置项来覆盖默认配置:
-
-```ts
-export default {
-  tools: {
-    tsLoader: {
-      allowTsInNodeModules: false,
-    },
-  },
-};
-```
-
-### Function 类型
-
-当此值为 Function 类型时，默认配置作为第一参数传入，可以直接修改配置对象，也可以返回一个对象作为最终配置；第二个参数为修改 `ts-loader` 配置工具函数集合：
-
-```ts
-export default {
-  tools: {
-    tsLoader: opts => {
-      opts.allowTsInNodeModules = false;
-    },
-  },
-};
-```
-
-### 工具函数
-
-#### addIncludes
-
-已废弃，请使用 [source.include](https://modernjs.dev/configure/app/source/include.html) 代替，两者功能完全一致。
-
-#### addExcludes
-
-已废弃，请使用 [source.exclude](https://modernjs.dev/configure/app/source/exclude.html) 代替，两者功能完全一致。