@modern-js/main-doc 2.22.0 → 2.22.1

package/docs/en/guides/get-started/quick-start.mdx

@@ -13,16 +13,16 @@ import Prerequisites from "@site-docs-en/components/prerequisites"
 
 ## Installation
 
-Modern.js provides the `@modern-js/create` tool for creating new projects. You can use `npx` to run it.
+Modern.js provides the `@modern-js/create` tool to create projects. Do not install it globally, use `npx` to run it.
 
-You can create the project in an existing empty directory:
+You can create a project in an existing empty directory:
 
 ```bash
 mkdir myapp && cd myapp
 npx @modern-js/create@latest
 ```
 
-You can also directly create the project as a new folder:
+You can also create a project directly in a new directory:
 
 ```bash
 npx @modern-js/create@latest myapp
@@ -36,31 +36,15 @@ import InitApp from "@site-docs-en/components/init-app"
 
 ## Development
 
-Execute `pnpm run dev` in the project to start the project:
+import DebugApp from "@site-docs-en/components/debug-app"
 
-```bash
-$ pnpm run dev
-
-> modern dev
-
-info    Starting dev server...
-info    App running at:
-
-  > Local:    http://localhost:8080/
-  > Network:  http://192.168.0.1:8080/
-
- Client ✔ done in 76.10ms
-```
-
-Open `http://localhost:8000/` in your browser and you will see the following:
-
-![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+<DebugApp />
 
 ## Configuration
 
-The `modern.config.ts` files exist in Modern.js projects created by the generator.
+In a Modern.js project created using `@modern-js/create`, a `modern.config.ts` file is generated by default.
 
-Features can be enabled through the configuration file, or the default behavior of the coverage Modern.js. For example, add the following configuration to enable SSR:
+You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
@@ -76,11 +60,11 @@ export default defineConfig({
 });
 ```
 
-Re-execute `pnpm run dev`, in the browser Network menu, you can find that the project has completed page rendering at the server level.
+After running `pnpm run dev` again, you can find that the project has completed page rendering on the server in the browser's Network menu.
 
-## Build
+## Build the project
 
-Execute `pnpm run build` in the project to build the project production environment product:
+To build the production artifacts of the project, run `pnpm run build` in the project:
 
 ```bash
 $ pnpm run build
@@ -106,27 +90,25 @@ info    File sizes after production build:
  Client ✔ done in 3.57s
 ```
 
-The bundle is generated to `dist/` by default, and the directory structure is as follows:
+By default, the build artifacts are generated in `dist/`, with the following directory structure:
 
 ```
-.
-├── asset-manifest.json
+dist
 ├── html
-│   └── main
-├── loader-routes
-│   └── main
+│   └── main
 ├── modern.config.json
 ├── route.json
+├── routes-manifest.json
 └── static
     ├── css
     └── js
 ```
 
-> If you want to customize the output directory, please refer to [Output Files](https://modernjs.dev/builder/en/guide/basic/output-files.html).
+> If you need to customize the directory of the build artifacts, please refer to [Output files](https://modernjs.dev/builder/guide/basic/output-files.html).
 
 ## Verify
 
-Execute `pnpm run serve` in the project to verify locally that the bundle is running correctly:
+Run `pnpm run serve` in the project to verify whether the build artifacts run normally locally:
 
 ```bash
 $ pnpm run serve
@@ -140,8 +122,10 @@ info    App running at:
   > Network:  http://192.168.0.1:8080/
 ```
 
-Open http://localhost:8000/ in the browser and the content should be the same as when `pnpm run dev`.
+Open `http://localhost:8000/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+
+## Deployment
 
-## Deploy
+import Deploy from "@site-docs-en/components/deploy"
 
-Once the local verification is complete, the outputs under `dist` folder can be organized into the structure required by the server for deployment.
+<Deploy />

package/docs/en/guides/get-started/upgrade.mdx

@@ -7,40 +7,42 @@ sidebar_position: 3
 
 ## Upgrade with command
 
-Modern.js provides the `upgrade` command to support projects to upgrade to the latest version.
+Modern.js provides the `upgrade` command to support upgrading the project to the latest version of Modern.js.
 
-Execute `pnpm run upgrade` in the project:
+Run `pnpm run upgrade` in the project:
 
 ```bash
 $ pnpm run upgrade
 
 > modern upgrade
 
-[INFO] [Project Type]: Application
+[INFO] [Project Type]: Web App
 [INFO] [Modern.js Latest Version]: 2.0.0
 [INFO] Upgrade Modern.js package version success!
 ```
 
-You can see that the dependency in the project `package.json` has been changed to the latest.
+You can see that the dependencies in the project's `package.json` have been updated to the latest version.
 
-## Specify version upgrade
+## Upgrade to a specified version
 
-All packages of Modern.js are published using the **unified version number**.
+All packages of Modern.js are currently released with a **uniform version number**.
 
-According to the website release note, developers can also manually upgrade the project to the desired version.
+import ReleaseNote from "@site-docs-en/components/release-note"
+
+<ReleaseNote />
 
 :::tip
-When upgrading, you need to upgrade to all packages provided by the Modern.js, rather than upgrading a single dependency.
+When upgrading, you need to upgrade all packages provided by Modern.js, instead of upgrading a single dependency.
 
 :::
 
 ## Lock nested dependency
 
-When there is a problem with one of the nested dependencies of the project, and the Modern.js cannot be updated immediately, you can use the package manager to lock the child dependency version.
+When a nested dependency of the project has a problem and Modern.js cannot be updated immediately, you can use the package manager to lock the version of the nested dependency.
 
 ### pnpm
 
-For projects using pnpm, add the following configuration to the `package.json` in the **project root directory** and re-execute `pnpm install`:
+For projects using pnpm, add the following configuration to the `package.json` in the **root directory** of the project, and then run `pnpm install` again:
 
 ```json title="package.json"
 {
@@ -54,7 +56,7 @@ For projects using pnpm, add the following configuration to the `package.json` i
 
 ### Yarn
 
-For projects using Yarn, add the following configuration to the `package.json` in the **project root directory** and re-execute `yarn install`:
+For projects using Yarn, add the following configuration to the `package.json` in the **root directory** of the project, and then run `yarn install` again:
 
 ```json title="package.json"
 {
@@ -66,7 +68,7 @@ For projects using Yarn, add the following configuration to the `package.json` i
 
 ### Npm
 
-For projects using Npm, add the following configuration to the `package.json` in the **project root directory** and re-execute `npm install`:
+For projects using Npm, add the following configuration to the `package.json` in the **root directory** of the project, and then run `npm install` again:
 
 ```json title="package.json"
 {
@@ -77,6 +79,6 @@ For projects using Npm, add the following configuration to the `package.json` in
 ```
 
 :::info
-For Monorepo repositories, the dependency version can only be locked in the `package.json` in the project root directory, and all packages in Monorepo are affected.
+For Monorepo repositories, you can only lock dependency versions in the `package.json` in the root directory of the project, and it will affect all packages in the Monorepo.
 
 :::

package/docs/en/guides/topic-detail/changesets/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Package Version Management",
+  "position": 5
+}

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

@@ -0,0 +1,125 @@
+---
+sidebar_position: 2
+---
+
+# Add Changesets
+
+When we finish development, we need to add a changeset to declare the current changes for version releases.
+
+## Information
+
+A changeset includes:
+
+- Which packages are affected by this change.
+
+- The type of version for this change, which complies with the [semver](https://semver.org/) specification.
+
+- Changelog information for this change.
+
+## 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 change command in the root directory:
+
+```bash
+pnpm run change
+```
+
+#### Select the type of version for this change
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-version.png)
+
+#### Fill in the changelog information
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog.png)
+
+After running, a corresponding changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+'module-changeset': patch
+---
+
+feat: test module solution changeset
+```
+
+This file contains all the information of the changeset.
+
+### Monorepo
+
+There are three NPM module packages in the monorepo, `module-1`, `module-2`, and `module-3`.
+
+#### Run the change command in the root directory
+
+```bash
+pnpm run change
+```
+
+#### Select the list of packages to upgrade for this change
+
+Changesets will categorize the packages in the Monorepo into two categories, `changed packages` and `unchanged packages`, based on the current code changes (`git diff Head...baseBranch`), making it easy for users to choose.
+
+Use the space key to select the corresponding package or category, and then press Enter after the selection is completed:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-packages.png)
+
+#### Select the packages corresponding to different version types
+
+Changesets will ask about the `major` and `minor` types. If there are packages that have not selected these two types, the `patch` type will be used by default.
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-auto-select-patch.png)
+
+#### Fill in the changelog information
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog-monorepo.png)
+
+After running, a corresponding changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+'module-2': minor
+'module-3': patch
+---
+
+feat: test-changeset
+```
+
+This file contains all the information of the changeset, and different packages will be marked according to the selected version type.
+
+## Parameters
+
+The `change` command supports the following parameters:
+
+- `--empty`: Adds an empty changeset.
+
+```bash
+pnpm run change --empty
+```
+
+After running, an empty changeset file will be created in the `.changeset` directory of the project, and the file content is as follows:
+
+```markdown
+---
+---
+```
+
+- `--open`: When using this parameter, the system default editor will be opened for filling in the changelog.
+
+## Notes
+
+- Not all changes require changesets
+
+If the current change is to modify some infrastructure of the repository, such as CI, testing, etc., there is no need to add changesets, or an empty changeset can be added.
+
+- Multiple changesets can be submitted in one pull request
+
+When a pull request has multiple feature developments or bug fixes, multiple `pnpm run change` commands can be executed to add multiple changeset files. Each file selects the corresponding packages for the feature and adds change information.
+
+- When creating a changeset, all packages related to the feature need to be selected
+
+When creating a changeset in a Monorepo, all related packages to the feature need to be selected to avoid some packages not being published when releasing.

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

@@ -0,0 +1,238 @@
+---
+sidebar_position: 6
+---
+
+# Customizing Changelog
+
+By default, Changesets will use `@changesets/cli/changelog` to generate changelog. If the default changelog cannot meet the requirements, you can customize the generation of changelog.
+
+## Customizing Changelog Content
+
+Changelog mainly includes the following two types of information:
+
+- Changelog written in the changeset.
+
+- Version change information of related packages in this version upgrade.
+
+The custom logic mainly implements two functions, `getReleaseLine` and `getDependencyReleaseLine`, which are used to define the above two types of information, respectively.
+
+### getReleaseLine
+
+#### Params
+
+- changeset
+
+```ts
+export type VersionType = 'major' | 'minor' | 'patch' | 'none';
+
+export type Release = { name: string; type: VersionType };
+
+export type Changeset = {
+  id: string; // changeset id
+  commit?: string; // changeset commit id
+  summary: string; // changeset summary content
+  releases: Array<Release>; // The name and type information of the current computed changeset upgrade package.
+};
+```
+
+- type
+
+The upgraded version type corresponding to the current package, which is of type `VersionType` mentioned above.
+
+#### Returns
+
+Changelog content.
+
+#### Default Implementation
+
+The default processing logic of `@changesets/cli/changelog` is to split the `summary` information according to the newline `\n`, add `-` as the list header before the first line, and organize other content as the supplement of the first line below the list.
+
+```ts
+async function getReleaseLine(changeset, type) {
+  const [firstLine, ...futureLines] = changeset.summary
+    .split('\n')
+    .map(l => l.trimRight());
+
+  let returnVal = `- ${
+    changeset.commit ? `${changeset.commit}: ` : ''
+  }${firstLine}`;
+
+  if (futureLines.length > 0) {
+    returnVal += `\n${futureLines.map(l => `  ${l}`).join('\n')}`;
+  }
+
+  return returnVal;
+}
+```
+
+### getDependencyReleaseLine
+
+#### Params
+
+- changesets
+
+All associated changeset information, which is an array of `getReleaseLine` changeset types.
+
+- dependenciesUpdated
+
+```ts
+type ModCompWithPackage = {
+  name: string; // Name of the dependent module
+  type: VersionType; // Upgrade type of the dependent module
+  oldVersion: string; // Current version of the dependent module
+  newVersion: string; // New version of the dependent module
+  changesets: string[]; // List of associated changeset ids
+  packageJson: PackageJSON; // Complete package.json content of the dependent module
+  dir: string; // Path (absolute path) of the dependent module
+};
+
+type DependenciesUpdated = ModCompWithPackage[];
+```
+
+#### Returns
+
+Changelog content.
+
+#### Default Implementation
+
+By default, `@changesets/cli/changelog` will display the corresponding `Updated dependencies + commit id` information of the changesets as a list. Then, based on the `dependenciesUpdated` information, it will display the package name and new version of the corresponding dependency package as a child list item of the list.
+
+```ts
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
+  console.log('getDependencyReleaseLine', changesets, dependenciesUpdated);
+  if (dependenciesUpdated.length === 0) return '';
+
+  const changesetLinks = changesets.map(
+    changeset =>
+      `- Updated dependencies${
+        changeset.commit ? ` [${changeset.commit}]` : ''
+      }`,
+  );
+
+  const updatedDepenenciesList = dependenciesUpdated.map(
+    dependency => `  - ${dependency.name}@${dependency.newVersion}`,
+  );
+
+  return [...changesetLinks, ...updatedDepenenciesList].join('\n');
+}
+```
+
+It is displayed as follows:
+
+```markdown
+- Updated dependencies [f0438ab]
+- Updated dependencies [f0438ab]
+  - module-3@2.0.0
+  - module-1@0.2.0
+```
+
+## Configuration
+
+The `changelog` field in the changesets configuration file is used to mark the way to get changelog.
+
+This configuration can be a string, directly declaring the module name or path of the changelog module.
+
+This configuration also supports configuring arrays. The first element in the array is the module name or path of the changelog module, and the second element is the parameter value passed to the corresponding function, which will be passed as the third parameter of the `getReleaseLine` and `getDependencyReleaseLine` functions.
+
+### Configuring Relative Paths
+
+If the changelog configuration is a relative path, it is a relative path under the `.changesets` directory.
+
+For example, create the `.changeset/my-changelog-config.js` file and define the following content:
+
+```ts title=".changeset/my-changelog-config.js"
+async function getReleaseLine(changeset, type) {}
+
+async function getDependencyReleaseLine(changesets, dependenciesUpdated) {}
+
+module.exports = {
+  getReleaseLine,
+  getDependencyReleaseLine,
+};
+```
+
+Configure `changlog` as `./my-changelog-config.js`:
+
+```json title=".changesets/config.json"
+{
+  "changelog": "./my-changelog-config.js",
+   ...
+}
+```
+
+### Using Npm Module
+
+Customizing changelog 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-changelog
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### Publish the module to NPM
+
+#### Install the module in the root directory of the target repository, such as `custom-changelog`.
+
+#### Configure the changelog configuration of changesets as the package name.
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+### 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 NPM module sub-project
+
+```bash
+? Please select the type of project you want to create: Npm Module
+? Please fill in the sub-project name: custom-changelog
+? Please fill in the sub-project directory name: custom-changelog
+? Please select the programming language: TS
+```
+
+#### Implement Custom Content
+
+```ts title="src/index.ts"
+export async function getReleaseLine() {}
+
+export async function getDependencyReleaseLine() {}
+```
+
+#### Add the sub-project module dependency, such as `custom-changelog`, to the Monorepo root directory
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "custom-changelog": "workspace: *",
+    ...
+  }
+}
+```
+
+#### Configure the changelog configuration of Changesets as the package name
+
+```json title=".changesets/config.json"
+{
+  "changelog": "custom-changelog",
+   ...
+}
+```
+
+After the module is published to NPM, it can still be used like a module type for other repositories.