@modern-js/main-doc 2.22.0 → 2.22.1

package/docs/en/guides/topic-detail/changesets/release-note.mdx

@@ -0,0 +1,273 @@
+---
+sidebar_position: 8
+---
+
+# Customizing Release Note Format
+
+Modern.js provides the `modern gen-release-note` command, which supports automatically generating Release Note through the current existing changeset and git commit information. Before running the release command, you can run this command to generate the Release Note for this release.
+
+The default generated Release Note format is:
+
+```markdown
+- fix: add missing type definitions by @zllkjc in https://github.com/web-infra-dev/modern.js/pull/3835
+```
+
+Get the Pull Request ID of the changeset through the commit information, and generate a Github link, which includes the changeset's changelog information and author information.
+
+:::info
+To get author information, you need to provide the Github Token environment variable, which is passed in through GITHUB_AUTH_TOKEN.
+:::
+
+When the default generated Release Note logic cannot meet the requirements, custom Release Note format is supported.
+
+## Information
+
+### getReleaseInfo
+
+To generate Release Note information, some information needs to be collected, such as commit ID, Pull Request ID, commit message, etc.
+
+This logic can be implemented through the `getReleaseInfo` function.
+
+#### Params
+
+- commit
+
+Type: string;
+
+The commit message information corresponding to the current changeset.
+
+The result of executing `git log --pretty=format:%h--%s--%ae .changeset/${changeset.id}.md`.
+
+- commitObj
+
+Basic information about commit.
+
+```ts
+export enum CommitType {
+  Performance = 'performance',
+  Features = 'features',
+  BugFix = 'bugFix',
+  Doc = 'doc',
+  Other = 'other',
+}
+
+interface Commit {
+  id: string; // commit id
+  type: CommitType;
+  repository?: string; // Repo information passed in as a parameter or defined in package.json
+  pullRequestId?: string;
+  author?: string;
+  message: string; // Commit message
+  summary: string; // Changeset summary
+  summary_zh: string; // Changeset summary in Chinese
+  [key: string]: string | undefined;
+}
+```
+
+#### Returns
+
+commitObj, the complete commit object after supplementation.
+
+#### Default Implementation
+
+The default implementation of Modern.js is to split out the Pull Request ID based on the commit information, and get the user information based on the commit ID and add it to the commitObj.
+
+```ts
+function getReleaseInfo(commit: string, commitObj: Commit) {
+const commitRegex = /(.*)\(#(\d*)\)/;
+
+  const [commitId, message, email] = commit.split('--');
+
+  const author = AuthorMap.get(email);
+  const token = authToken || process.env.GITHUB_AUTH_TOKEN;
+  if (author) {
+    commitObj.author = author;
+  } else if (repo && token) {
+    try {
+      const res = await axios.get(
+        `https://api.github.com/repos/${repo}/commits/${commitId}`,
+        {
+          method: 'GET',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: token,
+          },
+        },
+      );
+      const author = res.data.author.login;
+      commitObj.author = author;
+      AuthorMap.set(email, author);
+    } catch (e) {
+      console.warn(e);
+    }
+  }
+
+  if ((message || commitObj.summary).match(commitRegex)) {
+    const [, messageShort, pullRequestId] = (
+      message || commitObj.summary
+    ).match(commitRegex)!;
+    commitObj.pullRequestId = pullRequestId;
+    commitObj.message = messageShort.trim();
+  }
+
+  return commitObj;
+}
+```
+
+### getReleaseNoteLine
+
+Generate the corresponding Release Note based on the commit object information getted in `getReleaseInfo`.
+
+This logic can be implemented through the `getReleaseNoteLine` function.
+
+#### Params
+
+- commit
+
+The type is the same as the above `commitObj` type.
+
+- lang
+
+Type: string;
+
+Get the Release Note information of the corresponding language, supporting `en` and `zh`, the default is `en`.
+
+#### Returns
+
+The generated Release Note.
+
+#### Default Implementation
+
+The default implementation of Modern.js is:
+
+```ts
+export function getReleaseNoteLine(
+  commit: Commit,
+  lang: 'en' | 'zh' = 'en',
+) {
+  const { repository, pullRequestId, summary, summary_zh, author } = commit;
+  const pullRequest =
+    pullRequestId && repository
+      ? `https://github.com/${repository}/pull/${pullRequestId}`
+      : '';
+  if (lang === 'en') {
+    return `- ${summary}${author ? ` by @${author}` : ''}${
+      pullRequest ? ` in ${pullRequest}` : ''
+    }\n`;
+  }
+  return `- ${summary_zh}${author ? ` 由 @${author} 实现` : ''}${
+    pullRequest ? `， 详情可查看 ${pullRequest}` : ''
+  }\n`;
+}
+```
+
+## Using Custom Modules
+
+The `gen-release-note` command supports the `--custom` parameter, which can pass in the module name or path of the custom Release Note module.
+
+### Configuring Relative Paths
+
+If the custom parameter value is a relative path, it is the **project root directory**.
+
+For example, create the `scripts/my-release-note-config.js` file and define the following content:
+
+```ts title="scripts/my-release-note-config.js"
+function getReleaseInfo(commit, commitObj) {
+  return commitObj;
+}
+
+function getReleaseNoteLine(commit) {}
+
+module.exports = {
+  getReleaseInfo,
+  getReleaseNoteLine,
+};
+```
+
+Run the following command:
+
+```bash
+pnpm run gen-release-note --custom ./scripts/my-release-note-config.js
+```
+
+You can also define the command parameters directly in `package.json`:
+
+```json title="package.json"
+{
+    "scripts": {
+        ...
+        "gen-release-note": "modern gen-release-note --custom ./scripts/my-release-note-config.js"
+    },
+    ...
+}
+```
+
+Run the command `pnpm run gen-release-note` directly.
+
+### Using NPM Module
+
+Customizing release note can also be managed using the NPM module project to provide a common solution.
+
+#### Use `npx @modern-js/create@latest` to create a module project
+
+```md
+? Please select the type of project you want to create: Npm Module
+? Please fill in the project name: custom-release-note
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+#### Publish the module to NPM
+#### Install the corresponding module in the root directory of the target repository, such as `custom-release-note`
+#### Run the `gen-release-note` command with the `custom` parameter added
+
+```bash
+pnpm run gen-release-note --custom custom-release-note
+```
+
+### Using Monorepo Sub-Project
+
+If your current repository is Monorepo, you can directly manage it using NPM module sub-projects.
+
+#### Run `pnpm run new` to create a module sub-project
+
+```md
+? Please select the type of project you want to create: Npm Module
+? Please fill in the sub-project name: custom-release-note
+? Please fill in the sub-project directory name: custom-release-note
+? Please select the programming language: TS
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export function getReleaseInfo() {}
+
+export function getReleaseNoteLine() {}
+```
+
+#### Add the sub-project module dependency, such as `custom-release-note`, to the Monorepo root directory
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-release-note": "workspace: *",
+    ...
+}
+```
+
+#### Run the `gen-release-note` command with the `custom` parameter added
+
+```bash
+pnpm run gen-release-note --custom custom-release-note
+```
+
+After the module is published to NPM, it can still be used like a module type for other repositories.

package/docs/en/guides/topic-detail/changesets/release-pre.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_position: 4
+---
+
+# Publishing Pre-Release Version
+
+Before doing an actual release, we also need to publish a pre-release version for internal testing and user use. Changesets also support publishing pre-release versions.
+
+## Steps
+
+:::info
+The following example commands are all using pnpm. If you need to use other package management tools, please replace them as needed.
+:::
+
+#### Run the bump command to upgrade the version of the pre-release
+
+```bash
+pnpm run bump --canary --preid <preid>
+```
+
+`preid` is the tag for the pre-release version, such as `alpha`, `beta`, etc., and the default value is `next`.
+
+After using the `--canary` parameter, the `bump` command completes the following three steps:
+
+- `changeset pre enter <preid>`: Enters pre-release mode.
+
+- `changeset version`: Upgrades the version.
+
+- `changeset pre exit`: Exits pre-release mode.
+
+#### Check the changes and submit
+
+Check whether the version changes are correct and submit the changes.
+
+It is recommended to perform pre-release operations not on the main branch and not merge them into the main branch. After the pre-release verification is completed, an actual version can be directly released based on the main branch.
+
+#### Run the release command to publish the pre-release version:
+
+```bash
+pnpm run release --tag <tag>
+```
+
+When publishing a pre-release version, you must use the `--tag` parameter. The parameter value is best the same as the `preid` value to facilitate user use.
+
+## Notes
+
+### Exiting pre-release mode
+
+After entering pre-release mode, changesets will automatically create a `pre.json` file in the `.changeset` directory to record some status information when entering pre-release mode. When the status information is inconsistent with the current repository status, you can directly delete this file to exit pre-release mode.

package/docs/en/guides/topic-detail/changesets/release.mdx

@@ -0,0 +1,229 @@
+---
+sidebar_position: 3
+---
+
+# Publishing Version
+
+When releasing a version, we need to upgrade the version of the corresponding packages based on the changeset generated during development, and run the publish command to publish them to NPM.
+
+## Steps
+
+:::info
+The following example commands are all using pnpm. If you need to use other package management tools, please replace them as needed.
+
+:::
+
+### Npm Module
+
+#### Run the bump command in the root directory
+
+```bash
+pnpm run bump
+```
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-bump.png)
+
+When running this command, changesets will automatically perform the following operations:
+
+- Delete all changeset files under the `.changesets` directory.
+
+- Upgrade the package version based on the changeset information.
+
+- Write changelog information to the `CHANGELOG.md` file in the root directory. The file will be automatically created if it does not exist.
+
+#### Confirm and submit the current changes
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### Run the release command in the root directory to publish the package to NPM
+
+```bash
+pnpm run release
+```
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-module-release.png)
+
+#### Push the tag to the remote repository
+
+```bash
+git push --follow-tags
+```
+
+### Monorepo
+
+#### Run the bmp command in the root directory
+
+```bash
+pnpm run bump
+```
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-monorepo-bump.png)
+
+When running this command, changesets will automatically perform the following operations:
+
+- Delete all changeset files under the `.changesets` directory.
+
+- Upgrade the version of the relevant packages based on the changeset information. In addition to the packages written in the changeset, changesets will also analyze the dependency graph of all packages in the Monorepo during running. If is required, the version will be automatically upgraded accordingly.
+
+- Write changelog to the `CHANGELOG.md` file in the directory of the package that needs to be upgraded. The file will be automatically created if it does not exist.
+
+#### Confirm and submit the current changes
+
+:::info
+Make sure that the automatically upgraded version meet the expected requirements. If you need to understand the version upgrade strategy, please refer to [Version Upgrade Strategy](/guides/topic-detail/changesets/release#version-upgrade-strategy).
+:::
+
+```bash
+git add .
+git commit -m "release: bump package"
+```
+
+#### Run the release command in the root directory to publish the package to NPM
+
+```bash
+pnpm run release
+```
+
+When running this command, it will sequentially determine whether the versions of all packages in the Monorepo exist on NPM. If they do not exist, the `publish` command will be run to publish them.
+
+:::warning
+When the dependencies between packages in the Monorepo are declared using workspace, do not directly run `npm publish` to publish the package in the corresponding subdirectory of the package. Use the `release` command instead. When publishing, the workspace declaration will be automatically removed to ensure that the NPM package is available after publishing.
+:::
+
+#### Push the tag to the remote repository
+
+```bash
+git push --follow-tags
+```
+
+## Parameters
+
+### Parameters for the `bump` command
+
+- `--snapshot`: Generates a timestamp-based version.
+
+```bash
+pnpm run bump --snapshot canary
+```
+
+After running, the corresponding upgraded version will become `0.0.0-canary-20220622092823`, and `canary` is the tag configured for snapshot. If not configured, it will directly generate the form of `0.0.0-20220622092823`.
+
+This parameter is mainly used to publish temporary test versions for testing and does not require code submission.
+
+- `--ignore`: Manually ignore some packages during publishing.
+
+For example, if you need to ignore the `module-2` package for this release:
+
+```bash
+pnpm run bump --ignore module-2
+```
+
+After running the command, the update of the `module-2` package will be ignored. Note that if there are packages that depend on `module-2`, the corresponding packages also need to be added to the `ignore` parameter, otherwise the `bump` command will fail.
+
+The usage for adding multiple packages is as follows:
+
+```bash
+pnpm run bump --ignore module-2 --ignore module-3
+```
+
+### Parameters for the `release` command
+
+- `--otp`: Uses `npm token` to publish the package.
+
+```bash
+pnpm run relese --otp <token>
+```
+
+- `--tag`: Uses a specific tag for publishing, and `latest` is used by default.
+
+```bash
+pnpm run release --tag <tag>
+```
+
+- `--ignore-scripts`: Ignores npm scripts during publishing.
+
+When running the `publish` command, npm will automatically trigger many commands, such as `prepare` and `prepublish`. Using this parameter can ignore the running of these commands. This parameter is only supported in Monorepo using pnpm.
+
+```bash
+pnpm run release --ignore-scripts
+```
+
+- `--no-git-checks`: Ignores checking the current branch during publishing.
+
+By default, when running the `release` command, it will automatically check whether the current branch is a release branch, whether there are uncommitted changes, etc. Using this parameter can ignore git-related checks.
+
+```bash
+pnpm run release --no-git-checks
+```
+
+## Version Upgrade Strategy
+
+### dependencies or devDependencies
+
+- Only upgrade the patch version of the package itself for patch version
+
+For example, the following scenario exists:
+
+There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `dependencies` of `module-2`.
+
+The current changeset is the patch version upgrade of `module-1`.
+
+After running the `bump` command, only the patch version of `module-1` will be upgraded.
+
+- Upgrade the major or minor version of the package itself for major/minor version upgrades, and upgrade the patch version of the dependent packages
+
+For example, the following scenario exists:
+
+There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `dependencies` of `module-2`.
+
+The current changeset is the minor version upgrade of `module-1`.
+
+After running the `bump` command, `module-1` will upgrade the `minor` version, and `module-2` will upgrade the `patch` version number.
+
+### peerDependencies
+
+- Upgrade the patch version of the package itself and the dependent package for patch version dependencies
+
+For example, the following scenario exists:
+
+There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`.
+
+The current changeset is the patch version upgrade of `module-1`.
+
+After running the `bump` command, both `module-1` and `module-2` will upgrade the patch version.
+
+- Upgrade the major version of the dependent package for major/minor version upgrades of the package itself
+
+For example, the following scenario exists:
+
+There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`.
+
+The current changeset is the minor version upgrade of `module-1`.
+
+After running the bump command, `module-1` will upgrade the `minor` version, and `module-2` will upgrade the `major` version number.
+
+- Modify the upgrade strategy for peerDependencies
+
+The upgrade strategy of `peerDependencies` can be modified by configuring `onlyUpdatePeerDependentsWhenOutOfRange`. When only the declared version type range is exceeded, the corresponding `peerDependencies` will be upgraded.
+
+```json
+{
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  },
+  ...
+}
+```
+
+For example, the following scenario exists:
+
+There are two packages in Monorepo, `module-1` and `module-2`, and `module-1` exists in the `peerDependencies` of `module-2`, and the version of `module-1` is declared using `^`.
+
+The current changeset is the patch or minor version upgrade of `module-1`.
+
+After running the `bump` command, only the version of `module-1` will be upgraded.
+
+Note that if the package version is in the `0.x.x` range, upgrading the `minor` version is also beyond the declared version type range.

package/docs/en/guides/troubleshooting/builder.mdx

@@ -29,3 +29,11 @@ Please refer to [Modern.js Builder - Exceptions FAQ](https://modernjs.dev/builde
 - 'compilation' argument error when webpack compiling?
 - Compile error `You may need additional loader`?
 - Find `exports is not defined` runtime error?
+
+## HMR FAQ
+
+Please refer to [Modern.js Builder - HMR FAQ](https://modernjs.dev/builder/guide/faq/hmr.html), such as:
+
+- HMR not working when external React?
+- HMR not working when setting filename hash in development mode?
+- HMR not working when updating React components?

package/docs/zh/community/blog/v2-release-note.mdx

@@ -71,7 +71,7 @@ sidebar_position: 97
 
 <div style={{ textAlign: 'center', fontStyle: 'italic' }}>Rspack Logo</div>
 
-相较于 Webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，**Rspack 可以给 Modern.js 项目带来 5 ～ 10 倍编译性能的提升。**
+相较于 webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，**Rspack 可以给 Modern.js 项目带来 5 ～ 10 倍编译性能的提升。**
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/rspack-benchmark.png)
 

package/docs/zh/community/contributing-guide.mdx

@@ -120,7 +120,7 @@ pnpm run prepare
 如果你需要清理项目中的所有 `node_modules/*`，执行 `reset` 命令：
 
 ```sh
-pnpm 运行重置
+pnpm run reset
 ```
 
 ---

package/docs/zh/components/init-app.mdx

@@ -1,9 +1,10 @@
-Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+`@modern-js/create` 会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
 
 ```bash
-? 请选择你想创建的工程类型：Web 应用
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
+? 请选择你想创建的工程类型 Web 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择构建工具 webpack
 ```
 
 在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
@@ -20,11 +21,6 @@ pnpm run lint         # 运行 ESLint 并自动修复问题
 pnpm run new          # 启用可选功能或创建项目要素
 ```
 
-:::note
-Modern.js 生成器除了在项目初始化时工作外，也能在后续研发中生成项目各种粒度的模块，并非一用即抛开。
-
-:::
-
 现在，项目结构如下：
 
 ```

package/docs/zh/configure/app/output/css-modules.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: cssModules
+---
+
+# output.cssModules
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [output.cssModules](https://modernjs.dev/builder/api/config-output.html#outputcssmodules)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/output/cssModules.md';
+
+<Main />

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

@@ -19,23 +19,9 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 ## 安装
 
-首先，你需要执行 `pnpm run new` 启用 SWC 编译：
+import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enable-swc.md';
 
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「SWC 编译」
-```
-
-执行完成后，你只需在 `modern.config.ts` 文件中注册 SWC 插件，即可启用 SWC 编译和压缩能力。
-
-```ts title="modern.config.ts"
-import appTools, { defineConfig } from '@modern-js/app-tools';
-import swcPlugin from '@modern-js/plugin-swc';
-
-export default defineConfig({
-  plugins: [appTools(), swcPlugin()],
-});
-```
+<EnableSWC />
 
 ## 配置项
 

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -82,8 +82,7 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
       "@rspack/core": "nightly",
       "@rspack/dev-client": "nightly",
       "@rspack/dev-middleware": "nightly",
-      "@rspack/plugin-html": "nightly",
-      "@rspack/postcss-loader": "nightly"
+      "@rspack/plugin-html": "nightly"
     }
   }
 }

package/docs/zh/guides/concept/builder.mdx

@@ -14,7 +14,7 @@ Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向
 
 - 上层研发框架：Modern.js。
 - 通用构建引擎：Modern.js Builder。
-- 底层打包工具：webpack 和 rspack。
+- 底层打包工具：webpack 和 Rspack。
 
 <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ width: '100%', maxWidth: '540px' }} />