@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.3

package/zh/guides/basic-features/image.md

@@ -1,43 +0,0 @@
----
-title: 图片资源
-sidebar_position: 4
----
-
-## JS 中使用图片
-
-JS 文件中引入的图片资源会返回解析之后的 URL：
-
-```js title=src/App.jsx
-import logoUrl from './logo.png';
-
-console.log(logoUrl); // 输出： '/src/logo.png';
-```
-
-## Base64 编码内联
-
-默认情况下，小于 10kb 的图片、字体文件，会经过 Base64 编码，内联进页面，不会再发送独立的请求。
-
-可以通过配置 [`output.dataUriLimit`](/docs/configure/app/output/data-uri-limit) 修改这个阈值。
-
-## JS 中使用 SVG
-
-针对 SVG 资源，默认启用了 [SVGR](https://react-svgr.com/)，可以通过 React 组件的形式导入：
-
-```js title=App.jsx
-import logoUrl, { ReactComponent as LogoComponent } from './logo.svg';
-```
-
-## CSS 中使用图片
-
-在 CSS 文件中既可以通过相对路径也可以通过别名的方式引入图片:
-
-```css
-.logo {
-  background: url('./foo.png');
-}
-
-/** or **/
-.logo {
-  background: url('@/foo.png');
-}
-```

package/zh/guides/concept/integrated.md

@@ -1,4 +0,0 @@
----
-title: 一体化开发
-sidebar_position: 3
----

package/zh/guides/concept/solutions.md

@@ -1,4 +0,0 @@
----
-title: 工程方案
-sidebar_position: 4
----

package/zh/guides/topic-detail/compile-speed.md

@@ -1,182 +0,0 @@
----
-title: 提升编译速度
-sidebar_position: 9
----
-
-Modern.js 默认内置了一系列的编译性能优化策略，但是随着业务场景变复杂、仓库的代码量增大，在使用过程中可能会遇到一些编译性能的问题。
-
-本文档提供了一些可选的提速策略，**开发者可以根据实际场景选取其中的部分策略**，从而进一步提升编译速度。
-
-## 通用优化策略
-
-以下是一些通用的优化策略，对 `modern dev` 和 `modern build` 均有提速效果，其中部分策略对包体积也有优化。
-
-### 减少重复依赖
-
-在实际项目中，会存在某些第三方依赖被安装了多个版本的现象。重复依赖会导致包体积变大、编译速度变慢。
-
-我们可以通过社区中的一些工具来自动消除重复依赖，比如 [yarn-deduplicate](https://github.com/scinos/yarn-deduplicate)。
-
-```bash
-npx yarn-deduplicate && yarn
-```
-
-如果你在使用 `pnpm`，可以考虑通过**重新生成 lock 文件**来减少重复依赖，
-
-```bash
-rm -rf ./node_modules pnpm-lock.yaml && pnpm install
-```
-
-:::info
-删除 lock 文件会使项目中的依赖版本自动升级到指定范围下的最新版，请进行充分的测试。
-:::
-
-### 替换体积较大的依赖
-
-建议将项目中体积较大的第三方依赖替换为更轻量的库，比如将 [moment](https://momentjs.com/) 替换为 [day.js](https://day.js.org/)。
-
-如果不清楚项目中哪些三方依赖的体积较大，可以在执行构建时添加 `--analyze` 参数：
-
-```bash
-npx modern build --analyze
-```
-
-该参数会生成一个分析构建产物体积的 HTML 文件，手动在浏览器中打开该文件，可以看到打包产物的瓦片图。区块的面积越大，说明该模块的体积越大。
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-### 避免使用 ts-loader
-
-默认情况下，Modern.js 使用 Babel 编译 TS 文件，开启 `output.enableTsLoader` 选项后，会使用 `ts-loader` 编译 TS 文件。
-
-由于 `ts-loader` 需要进行额外的语法解析和类型检查，因此会导致项目编译速度变慢，请避免使用。
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  output: {
-    // 移除这项配置
-    enableTsLoader: true,
-  },
-});
-```
-
-详见 [tools.tsLoader 文档](/docs/configure/app/tools/ts-loader)。
-
-### 提升 Browserslist 范围
-
-**减少 Polyfill 的代码量可以提升编译速度。**Modern.js 会根据项目的 Browserslist 配置范围进行代码编译，并注入相应的 Polyfill。如果项目对兼容性的要求较低，可以根据实际情况，提升 Browserslist 范围，从而减少 Polyfill 的代码量。
-
-默认的 Browserslist 配置为：
-
-```js
-['> 0.01%', 'not dead', 'not op_mini all'];
-```
-
-比如只兼容 Chrome 53 以上的浏览器，可以改成：
-
-```js
-['Chrome >= 53'];
-```
-
-详见 [客户端兼容性 - Browserslist 配置](/docs/guides/advanced-features/compatibility#browserslist-配置)。
-
-### 按需引入 Polyfill
-
-明确第三方依赖不需要 Polyfill 的情况下，可以将 `output.polyfill` 设置为 `usage`，根据代码中使用到的语法，按需注入所需的 Polyfill 代码，从而减少 Polyfill 的代码量。
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  output: {
-    polyfill: 'usage',
-  },
-});
-```
-
-详见 [客户端兼容性 - Polyfill 模式](/docs/guides/advanced-features/compatibility#polyfill-模式)。
-
-## dev 优化策略
-
-以下是针对 `modern dev` 进行提速的策略。
-
-### 调整开发环境 SourceMap 格式
-
-为了提供良好的调试体验，Modern.js 在开发环境下默认使用 webpack 提供的 `cheap-module-source-map` 格式 SourceMap。
-
-由于生成高质量的 SourceMap 需要额外的性能开销，通过调整开发环境的 SourceMap 格式，可以提升 dev 编译速度。
-
-比如禁用 SourceMap：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    webpackChain(chain, { env }) {
-      if (env === 'development') {
-        chain.devtool(false);
-      }
-    },
-  },
-});
-```
-
-或是把开发环境的 SourceMap 格式设置为开销最小的 `eval` 格式：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    webpackChain(chain, { env }) {
-      if (env === 'development') {
-        chain.devtool('eval');
-      }
-    },
-  },
-});
-```
-
-> 关于不同 SourceMap 格式之间的详细差异，请查看 [webpack - devtool](https://webpack.js.org/configuration/devtool/)。
-
-### 调整开发环境的 Browserslist 范围
-
-这项优化的原理与「提升 Browserslist 范围」类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，使开发环境下不需要引入额外的 Polyfill 编译逻辑。
-
-比如在 `package.json` 中添加以下配置，在开发环境下只兼容最新的浏览器，在生产环境下兼容实际需要的浏览器：
-
-```json
-{
-  "browserslist": {
-    "production": [">0.2%", "not dead", "not op_mini all"],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  }
-}
-```
-
-注意，这项优化策略会导致 `dev` 构建的产物与 `build` 构建的产物存在一定差异。
-
-## build 优化策略
-
-以下是针对 `modern build` 进行提速的策略。
-
-### 禁用生产环境 SourceMap
-
-如果项目在生产环境下不需要 SourceMap，可以通过 `disableSourceMap` 配置项关闭，从而提升 build 构建的速度。
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  output: {
-    disableSourceMap: true,
-  },
-});
-```
-
-详见 [output.disableSourceMap](/docs/configure/app/output/disable-source-map)。
-
-### 使用 esbuild 压缩
-
-Modern.js 基于 esbuild 提供了代码编译和压缩的能力，在大型工程中开启后，**可以大幅度减少代码压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
-
-使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用（比较适合中后台场景）。
-
-详见 [tools.esbuild](/docs/configure/app/tools/esbuild)。

package/zh/guides/topic-detail/framework-plugin/abstract.md

@@ -1,27 +0,0 @@
----
-sidebar_position: 1
----
-
-# 插件可以做什么
-
-Modern.js 内置了一套插件系统，并基于这套插件系统来管理各个运行流程，Modern.js 的所有工程方案都是通过这套插件实现的，同时也支持开发者通过编写插件来扩展更多功能，适配复杂场景。
-
-由于 Modern.js 是基于这套插件系统实现的，因此可以说，Modern.js 中的所有能力是都对开发者开放的。包括但不限于：
-
-- 注册命令
-- 修改 Modern.js 配置、配置校验 Schema
-- 修改编译时的 Webpack/Babel/Less/Sass/Tailwind CSS/... 配置
-- 修改运行时需要渲染的 React 组件、Element
-- 修改页面路由
-- 修改服务器路由
-- 自定义控制台输出
-- 自定义动态 HTML 模版
-- 自定义 Node.js 服务器框架
-- 自定义 React 组件客户端/服务器端渲染
-- ...
-
-因此，当 Modern.js 暂时没有覆盖到你所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。
-
-:::info 补充信息
-关于 Modern.js 插件 API 的详细介绍，请参考 【[插件 API](/docs/apis/app/runtime/plugin/abstract)】。
-:::

package/zh/guides/troubleshooting/compile.md

@@ -1,379 +0,0 @@
----
-sidebar_position: 1
----
-
-# 编译构建问题
-
-### 如何配置 Webpack/Babel/PostCSS 等工具？
-
-请参考 [配置底层工具](/docs/guides/advanced-features/low-level)。
-
-### 如何自定义 HTML 模板？
-
-请参考 [自定义 HTML 模板](/docs/guides/basic-features/html)。
-
-### 如何提升编译构建速度？
-
-请参考 [提升编译速度](/docs/guides/topic-detail/compile-speed)。
-
-### 如何查看最终生效的 webpack 配置？
-
-可以通过 [modern inspect](/docs/apis/app/commands/inspect) 命令来查看最终生效的 webpack 配置。
-
----
-
-### 如何配置组件库按需引入？
-
-默认情况下，Modern.js 内置了 antd 组件库的按需引入配置。
-
-如果需要配置其他组件库的按需引入，可以通过 [tools.babel](/docs/configure/app/tools/babel) 配置 [babel-plugin-import](https://github.com/umijs/babel-plugin-import) 插件。
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    babel: (config, { addPlugins }) => {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ]);
-    },
-  },
-});
-```
-
----
-
-### 如何移除代码中的 console？
-
-在生产环境构建时，我们可以移除代码中的 `console`，从而避免开发环境的日志被输出到生产环境。
-
-由于 Modern.js 默认在生产环境使用 [terser](https://github.com/terser/terser) 进行代码压缩，因此我们可以通过 [tools.terser](/docs/configure/app/tools/terser) 配置项来移除 `console`：
-
-```js title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    terser: opt => {
-      if (typeof opt.terserOptions?.compress === 'object') {
-        opt.terserOptions.compress.drop_console = true;
-      }
-    },
-  },
-});
-```
-
-如果只希望移除 `console.log` 和 `console.warn`，保留 `console.error`，可以配置为：
-
-```js title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    terser: opt => {
-      if (typeof opt.terserOptions?.compress === 'object') {
-        opt.terserOptions.compress.pure_funcs = ['console.log', 'console.warn'];
-      }
-    },
-  },
-});
-```
-
----
-
-### 如何清空 webpack 编译缓存？
-
-默认情况下，Modern.js 的 webpack 编译缓存生成在 `./node_modules/.cache/webpack` 目录下。
-
-如果需要清空本地的编译缓存，可以执行以下命令：
-
-```bash
-rm -rf ./node_modules/.cache
-```
-
----
-
-### 如何配置静态资源的 CDN 路径？
-
-如果需要将 JS、CSS 等静态资源上传到 CDN 使用，那么可以通过 [output.assetPrefix](/docs/configure/app/output/asset-prefix) 配置来设置静态资源的 URL 前缀。
-
-```typescript title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  output: {
-    assetPrefix: 'https://cdn.example.com/assets/',
-  },
-});
-```
-
----
-
-### 如何在编译过程中进行 ESLint 代码校验？
-
-出于编译性能的考虑，Modern.js 默认不会在编译过程中进行 ESLint 校验，如果需要该功能，可以手动安装并注册社区中的 [eslint-webpack-plugin](https://github.com/webpack-contrib/eslint-webpack-plugin)。
-
-注册该插件的示例代码如下，更详细的用法请参考 [eslint-webpack-plugin](https://github.com/webpack-contrib/eslint-webpack-plugin) 文档。
-
-```typescript title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import ESLintPlugin from 'eslint-webpack-plugin';
-
-export default defineConfig({
-  tools: {
-    webpackChain(chain) {
-      chain.plugin('eslint-plugin').use(ESLintPlugin, [
-        {
-          extensions: ['.js', '.ts', '.jsx', 'tsx', '.mjs'],
-        },
-      ]);
-    },
-  },
-});
-```
-
----
-
-### 如何配置 SRI 校验？
-
-在 Modern.js 中，需要自主引入社区中的 [webpack-subresource-integrity](https://github.com/waysact/webpack-subresource-integrity) 插件来开启 SRI 校验。
-
-配置 [webpack-subresource-integrity](https://github.com/waysact/webpack-subresource-integrity) 的示例如下：
-
-```typescript title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import { SubresourceIntegrityPlugin } from 'webpack-subresource-integrity';
-
-export default defineConfig({
-  tools: {
-    webpackChain(chain) {
-      chain.output.crossOriginLoading('anonymous');
-      chain.plugin('subresource-integrity').use(SubresourceIntegrityPlugin);
-    },
-  },
-});
-```
-
-:::info SRI
-子资源完整性 Subresource Integrity（SRI）是专门用来校验资源的一种方案，它读取资源标签中的 integrity 属性，将其中的信息摘要值，和资源实际的信息摘要值进行对比，如果发现无法匹配，那么浏览器就会拒绝执行资源。
-
-对于 script 标签来说，结果为拒绝执行其中的代码；对于 CSS link 来说，结果为不加载其中的样式。
-:::
-
----
-
-### Less/Sass 代码没有被正确编译？
-
-Modern.js 通过插件来编译 Less/Sass 代码，请确认你是否启用了对应的插件。
-
-- [启用 Less 插件教程](/docs/configure/app/tools/less#启用)
-- [启用 Sass 插件教程](/docs/configure/app/tools/sass#启用)
-
----
-
-### 在 Monorepo 中引用其他模块，代码没有被正确编译？
-
-出于编译性能的考虑，默认情况下，Modern.js 不会通过 `babel-loader` 或 `ts-loader` 来编译 `node_modules` 下的文件，也不会编译当前工程目录外部的文件。
-
-通过 `source.include` 配置项，可以指定需要额外进行编译的目录或模块。
-
-详见 [source.include 用法介绍](/docs/configure/app/source/include/)。
-
----
-
-### 打包时出现 JavaScript heap out of memory?
-
-该报错表示打包过程中出现了内存溢出问题，大多数情况下是由于打包的内容较多，超出了 Node.js 默认的内存上限。
-
-如果出现 OOM 问题，最简单的方法是通过增加内存上限来解决，Node.js 提供了 `--max-old-space-size` 选项来对此进行设置。你可以在 `modern build` 命令前添加 [NODE_OPTIONS](http://nodejs.cn/api/cli/node_options_options.html) 来设置此参数：
-
-```bash
-NODE_OPTIONS=--max_old_space_size=16384 modern build
-```
-
-参数的值代表内存上限大小（MB)，一般情况下设置为 `16384`（16GB）即可。
-
-Node.js 官方文档中有对以下参数更详细的解释：
-
-- [NODE_OPTIONS](http://nodejs.cn/api/cli/node_options_options.html)
-- [--max-old-space-size](http://nodejs.cn/api/cli/max_old_space_size_size_in_megabytes.html)
-
-除了增加内存上限，通过开启一些编译策略来提升效率也是一个解决方案，详见 [提升编译速度](/docs/guides/topic-detail/compile-speed)。
-
----
-
-### webpack 编译出现 'compilation' argument 报错？
-
-如果编译时出现以下报错，通常是由于项目中安装了错误的 webpack 版本，或者安装了多个 webpack 版本引起：
-
-```bash
-TypeError: The 'compilation' argument must be an instance of Compilation
-```
-
-webpack 版本问题有以下几种情况：
-
-1. 项目的 package.json 中直接声明了 webpack 依赖，并且与 Modern.js 依赖的 webpack 版本范围不同，无法匹配到同一个版本。
-2. 项目里安装的多个 npm 包都依赖了 webpack，并且它们依赖的 webpack 版本范围不同，无法匹配到同一个版本。
-3. 由于包管理器的 lock 机制，导致 lock 文件中产生了多个 webpack 版本。
-
-如果是第一种情况，建议从项目的 package.json 中移除 webpack 依赖。因为 Modern.js 默认封装了 webpack 相关能力，并且会在 `tools.webpack` 配置项中传入 webpack 对象。因此在大多数情况下，不建议在项目中额外安装 webpack 依赖。
-
-如果是第二种情况，建议看看能否升级某个 npm 包，使其依赖的 webpack 版本范围与 Modern.js 保持一致。也可以通过包管理器的能力来手动统一版本，比如使用 [yarn resolutions](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) 或 [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides)。
-
-如果是第三种情况，可以使用第二种情况中提到的两种方法，也可以尝试删除 lock 文件后重新安装来解决。
-
-:::info
-删除 lock 文件会使项目中的依赖版本自动升级到指定范围下的最新版，请进行充分的测试。
-:::
-
----
-
-### Less 文件中的除法不生效？
-
-Less v4 版本与 v3 版本相比，除法的写法有一些区别：
-
-```less
-// Less v3
-.math {
-  width: 2px / 2; // 1px
-  width: 2px ./ 2; // 1px
-  width: (2px / 2); // 1px
-}
-
-// Less v4
-.math {
-  width: 2px / 2; // 2px / 2
-  width: 2px ./ 2; // 1px
-  width: (2px / 2); // 1px
-}
-```
-
-Modern.js 内置的 Less 版本为 v4，低版本的写法不会生效，请注意区分。
-
-Less 中除法的写法也可以通过配置项来修改，详见 [Less - Math](https://lesscss.org/usage/#less-options-math)。
-
----
-
-### 编译产物中存在未编译的 ES6+ 代码？
-
-默认情况下，Modern.js 不会通过 `babel-loader` 或 `ts-loader` 来编译 `node_modules` 下的文件。如果项目引入的 npm 包中含有 ES6+ 语法，会被打包进产物中。
-
-遇到这种情况时，可以通过 [source.include](/docs/configure/app/source/include) 配置项来指定需要额外进行编译的目录或模块。
-
----
-
-### 编译时报错 `You may need additional loader`？
-
-如果编译过程中遇到了以下报错提示，表示存在个别文件无法被正确编译。
-
-```bash
-Module parse failed: Unexpected token
-File was processed with these loaders:
- * some-loader/index.js
-
-You may need an additional loader to handle the result of these loaders.
-```
-
-解决方法：
-
-- 如果是引用了当前工程外部的 `.ts` 文件，或者是 node_modules 下的 `.ts` 文件，请添加 [source.include](/docs/configure/app/source/include) 配置项，指定需要额外进行编译的文件。
-- 如果是引用了 Modern.js 不支持的文件格式，请自行配置对应的 webpack loader 进行编译。
-
----
-
-### 打开页面后报错，提示 exports is not defined？
-
-如果编译正常，但是打开页面后出现 `exports is not defined` 报错，通常是因为在项目中使用 babel 编译了一个 CommonJS 模块，导致 babel 出现异常。
-
-在正常情况下，Modern.js 是不会使用 babel 来编译 CommonJS 模块的。如果项目中使用了 `source.include` 配置项，或使用了 `tools.babel` 的 `addIncludes` 方法，则可能会把一些 CommonJS 模块加入到 babel 编译中。
-
-该问题有两种解决方法：
-
-1. 避免将 CommonJS 模块加入到 babel 编译中。
-2. 将 babel 的 `sourceType` 配置项设置为 `unambiguous`，示例如下：
-
-```js
-export default defineConfig({
-  tools: {
-    babel(config) {
-      config.sourceType = 'unambiguous';
-    },
-  },
-});
-```
-
-将 `sourceType` 设置为 `unambiguous` 可能会产生一些其他影响，请参考 [babel 官方文档](https://babeljs.io/docs/en/options#sourcetype)。
-
----
-
-### 打包后发现 Tree Shaking 没有生效？
-
-Modern.js 在生产构建时会默认开启 webpack 的 Tree Shaking 功能，Tree Shaking 是否能够生效，取决于业务代码能否满足 webpack 的 Tree Shaking 条件。
-
-如果你遇到了 Tree Shaking 不生效的问题，可以检查下相关 npm 包的 `sideEffects` 配置是否正确，如果不了解 `sideEffects` 是什么，可以阅读以下两篇文档：
-
-- [webpack 官方文档 - Tree Shaking](https://webpack.docschina.org/guides/tree-shaking/)
-- [Tree Shaking 问题排查指南](https://bytedance.feishu.cn/docs/doccn8E1ldDct5uv1EEDQs8Ycwe)
-
----
-
-### 热更新后 React 组件的 state 丢失？
-
-Modern.js 使用 React 官方的 [Fast Refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) 能力来进行组件热更新。
-
-在使用 Fast Refresh 时，要求组件不能为匿名函数，否则热更新后无法保留 React 组件的 state。
-
-以下写法都是不正确的：
-
-```js
-// 错误写法 1
-export default function () {
-  return <div>Hello World</div>;
-}
-
-// 错误写法 2
-export default () => <div>Hello World</div>;
-```
-
-正确的写法为：
-
-```js
-// 正确写法 1
-export default function MyComponent() {
-  return <div>Hello World</div>;
-}
-
-// 正确写法 2
-const MyComponent = () => <div>Hello World</div>
-
-export default MyComponent;
-```
-
----
-
-### webpack 编译缓存未生效，应该如何排查？
-
-Modern.js 默认开启了 webpack 的持久化缓存。
-
-首次编译完成后，会自动生成缓存文件，并输出到 `./node_modules/.cache/webpack` 目录下。执行第二次编译时，会命中缓存，并大幅度提高编译速度。
-
-当 `modern.config.ts` 或 `package.json` 等配置文件被修改时，缓存会自动失效。
-
-如果项目中 webpack 编译缓存一直未生效，可以添加以下配置进行排查：
-
-```ts
-export default defineConfig({
-  tools: {
-    webpack(config) {
-      config.infrastructureLogging = {
-        ...config.infrastructureLogging,
-        debug: true,
-      };
-    },
-  },
-});
-```
-
-添加以上配置后，webpack 会输出日志用于 debug，请参考 `PackFileCacheStrategy` 相关的日志来了解缓存失效的原因。