@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/topic-detail/monorepo/publish.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 4
+---
+
+# 可复用模块的发布
+
+在 Monorepo 中有时会需要把多个模块项目发布到 [NPM](https://www.npmjs.com/) 上，本章将要介绍如果在 Monorepo 中对子项目进行版本更新以及发布。
+
+## 准备工作
+
+接着 [子项目联调](/docs/guides/topic-detail/monorepo/sub-project-interface) 章节的例子，我们对 `components` 模块进行发布。
+
+## 生成变更记录
+
+在开发阶段，当某个模块的功能开完完成之后，一般需要提交代码（例如提交到 [GitHub](https://github.com/) 上）并需要记录本次修改的内容。在 Modern.js 的 Monorepo 工程中，我们可以在 monorepo 根目录执行命令：
+
+```
+pnpm run change
+```
+
+然后根据提示选择变更或者将要发布的包以及选择包升级的版本，并填写变更信息。变更信息的内容可以包含此次开发的功能、修复的问题等。
+
+那么对于上面的例子，我们选择变更的项目为 `components`，并填写此次变更的内容：
+
+```
+$ modern change
+🦋  Which packages would you like to include? · components
+🦋  Which packages should have a major bump? · No items were selected
+🦋  Which packages should have a minor bump? · components
+🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋  Summary · add features
+🦋  === Releasing the following packages ===
+🦋  [Minor]
+🦋    components
+🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
+🦋  ║                                                      ========= NOTE ========                                                       ║
+🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
+🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+🦋  Is this your desired changeset? (Y/n) · true
+🦋  Changeset added! - you can now commit it
+🦋
+🦋  If you want to modify or expand on the changeset summary, you can find it here
+🦋  info /Users/demo/modern-js/official/monorepo-pnpm/.changeset/silent-tigers-run.md
+```
+
+该命令完成后，在 `.changeset` 中会有新的 `silent-tigers-run.md` 文件生成，其中包含了刚刚填写的信息，这些新生成的文件将用于后面发布流程中使用。**因此在提交代码的时候，需要将`.changeset` 目录下的文件一并提交**。
+
+## 版本更新
+
+在模块发布之前，还需要将模块的版本进行更新。。在 Modern.js 的 Monorepo 工程中，可以在 Monorepo 项目根目录下执行：
+
+```
+pnpm run bump
+```
+
+该命令会根据之前生成在 `.changeset` 目录下的文件自动更新对应模块的版本号和 CHANGELOG 信息，执行成功后会看到：
+
+```
+🦋  All files have been updated. Review them and commit at your leisure
+```
+
+## 发布
+
+最后执行 `pnpm run prepare --filter {./packages} && pnpm run release`，便可以发布对应的模块了。
+
+:::info 补充信息
+在上面的命令中 --filter {./packages} 用于筛选位于 `./packages` 目录下的子项目，可以通过 [PNPM Filtering](https://pnpm.io/filtering) 来了解更多它的使用。
+:::

package/zh/guides/topic-detail/monorepo/sub-project-interface.md

@@ -0,0 +1,170 @@
+---
+sidebar_position: 3
+---
+
+# 子项目联调
+
+本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
+
+## 准备工作
+
+按照 [「创建子项目」](/docs/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
+
+- 一个「应用」子项目
+- 一个「模块（内部）」子项目
+- 一个「模块」子项目
+
+执行 `pnpm run new`，并按照如下进行选择：
+
+**「应用」子项目：**
+```
+? 请选择你想创建的工程类型 应用
+? 请填写子项目名称 app
+? 请填写子项目目录名称 app
+? 请选择开发语言 TS
+? 是否需要支持以下类型应用 不需要
+? 是否需要调整默认配置? 否
+```
+
+**「模块（内部）」子项目：**
+```
+? 请选择你想创建的工程类型 模块（内部）
+? 请填写子项目名称 internal-lib
+? 请填写子项目目录名称 internal-lib
+? 请选择开发语言 TS
+```
+
+**「模块」子项目：**
+```
+? 请选择你想创建的工程类型 模块
+? 请填写子项目名称 components
+? 请填写子项目目录名称 components
+? 请选择开发语言 TS
+```
+
+创建成功后，会得到以下项目：
+
+- `./apps/app`
+- `./packages/components`
+- `./features/internal-lib`
+
+然后修改一下默认的代码和新增文件：
+
+**重命名 `./pakcages/components/src/index.tsx`**
+``` tsx
+import './index.css';
+
+export default function ({ text }: { text: string }) {
+  return (
+    <div>
+      This is UI Components Log: <p className="log">{text}</p>
+    </div>
+  );
+}
+```
+
+**新增 `./pakcages/components/src/index.css`**
+``` css
+.log {
+  color: gray;
+}
+```
+
+**修改 `./features/internal-lib/src/index.ts`**
+``` tsx
+export default function (text: string) {
+  return text.toUpperCase();
+}
+```
+
+**修改 `./apps/app/src/App.tsx`**
+``` tsx
+import { Switch, Route } from '@modern-js/runtime/router';
+import formatString from 'internal-lib';
+import Comp from 'components';
+
+import './App.css';
+
+const App = () => (
+  <Switch>
+    <Route exact={true} path="/">
+      <div className="container-box">
+        <Comp text={formatString('hello world')} />
+        {/* 省略... */}
+      </div>
+    </Route>
+    <Route path="*">
+      <div>404</div>
+    </Route>
+  </Switch>
+);
+
+export default App;
+```
+
+到此为止我们创建了一个可以被发布到外部的组件项目、一个转换字符串的内部模块项目以及一个使用组件和内部模块的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
+
+:::info 注
+启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
+:::
+
+由于Modern.js 支持 pnpm 与 Yarn 的 Monorepo 工程，接下来会从这两个方面分别介绍。
+
+## 在使用 pnpm 的 Monorepo 中进行项目联调
+
+在 pnpm 的 Monorepo 项目中，我们通过在 `apps/app` 子项目下分别执行：
+
+```
+pnpm add components
+```
+
+以及
+
+```
+pnpm add internal-lib -D
+```
+
+:::info 注
+注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
+:::
+
+将 `packages/components` 与 `features/internal-lib` 子项目加入到应用的依赖列表当中。
+
+执行成功后，在 `apps/app/package.json` 会发生如下变化：
+
+``` json
+{
+  "dependencies": {
+++  "components": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+++  "internal-lib": "workspace:^0.1.0"
+  },
+}
+```
+
+:::info 补充信息
+`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
+:::
+
+当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
+
+到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `features/internal-lib` 的源码，或者修改 `packages/components` 的源码并构建之后都会触发应用子项目的热更新。
+
+## 在使用 Yarn 的 Monorepo 中进行项目联调
+
+在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目和内部模块项目。
+
+:::info 补充信息
+之所以可以直接在应用中使用使用组件项目和内部模块项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
+:::
+
+但是由于组件 `components` 是非内部模块，因此建议在 `apps/app/package.json` 中进行依赖声明：
+
+``` json
+{
+  "dependencies": {
+++  "components": "0.1.0"
+  },
+}
+```

package/zh/guides/troubleshooting/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "常见问题",
+  "position": 6,
+  "collapsed": true
+}

package/zh/guides/troubleshooting/compile.md

@@ -0,0 +1,379 @@
+---
+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 前缀。
+
+```js title="modern.config.js"
+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) 文档。
+
+```js title="modern.config.js"
+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) 的示例如下：
+
+```js title="modern.config.js"
+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` 相关的日志来了解缓存失效的原因。