@modern-js/module-tools-docs 2.0.0-beta.4

package/docs/en/guide/basic/command-preview.md

@@ -0,0 +1,204 @@
+# Command Preview
+
+Commands available for module engineering projects.
+
+## `modern build`
+
+``` bash
+Usage: modern build [options]
+
+Build module command
+
+Options:
+  -w, --watch Build code in listening mode
+  --tsconfig [tsconfig] Specify the path to the tsconfig.json file (default:
+                         ". /tsconfig.json")
+  --platform [platform] Build products for all or specified platforms
+  --no-dts disables DTS type file generation and type checking
+  --no-clear disables automatic clearing of product output directories
+  -h, --help Show information about the current command
+```
+
+When you want to start a project build, you can execute the `modern build` command. When using this command, we can:
+
+- When wanting to start a build in watch mode, use the `--watch` option.
+- When you want to specify the path to the TypeScript configuration file read by the project build, use `-build --tsconfig . /path/config.json` option. This option overrides all [`buildConfig`](/zh/api/build-config) configurations in [`dts.tsconfigPath`](/zh/api/build-config).
+- The `-no-dts` option can be used when the DTS type file generation and type checking behavior of the project needs to be turned off. **Note: The generation of type files depends on the results of type checking. If type checking is turned off, then type files will not be generated either**.
+- The `--no-clear` option can be used when the automatic clearing of the product output directory needs to be turned off.
+
+In addition to the above, module projects also support `platform` build mode, which can be used to perform build tasks for other tools. For example, it is currently officially supported to start a Storybook build task to generate Storybook products by executing the `modern build --platform` or `modern build --platform storybook` commands after installing the `@modern-js/plugin-storybook` plugin.
+
+:::tip{title=Note}
+When executing a Storybook build, it needs to read the project's build product. So **when running the `modern build --platform` command to start a Storybook build, run `modern build` once to ensure that the source build product exists**.
+:::
+
+## `modern new`
+
+``` bash
+Usage: modern new [options]
+
+Execute the generator in a modular project scenario
+
+Options:
+  -d, --debug Enable Debug mode, print debug log messages (default: false)
+  -c, --config <config> Generators run default configuration (JSON string)
+  --dist-tag <tag> Generator uses a special version of npm Tag
+  --registry customize npm Registry during generator runtime
+  -h, --help display help for command
+```
+
+The `modern new` command is used to start the microgenerator functionality, which enables features for the project that are not provided by default.
+
+The following features can currently be enabled.
+
+- Storybook debugging
+- Tailwind CSS support
+- Modern.js Runtime API
+
+You can learn more about these features in the [Using the micro generator](/zh/guide/use-micro-generator) section.
+
+## `modern dev`
+
+``` bash
+Usage: modern dev [options]
+
+Local development commands
+
+Options:
+  -h, --help display help for command
+
+Commands:
+[dev-tools-subCommand]
+```
+
+The module engineering solution provides the ability to use debugging tools, which can be started with the `modern dev` command. Note, however, that no debugging-related plugins are provided by default, so executing `modern dev` will prompt: *"No dev tools found available "*.
+
+The officially supported debugging tool is [Storybook](https://storybook.js.org/), so you can run `modern dev` or `modern dev storybook` to execute it after you run `modern new` to enable it.
+
+## `modern test`
+
+``` bash
+Usage: modern test [options]
+
+Options:
+  -h, --help display help for command
+```
+The `modern test` command will automatically run the `src/tests/*.test.(js|ts|jsx|tsx)` file as a test case.
+
+
+## `modern lint`
+
+``` bash
+Usage: modern lint [options] [. .files]
+
+lint and fix source files
+
+Options:
+  --no-fix disable auto fix source file
+  -h, --help display help for command
+```
+
+Run [ESLint](https://eslint.org/) to check the syntax of the code. Usually, we only need to check the part of the code that was changed in this commit with [lint-staged](https://github.com/okonet/lint-staged) during the `-git commit` phase.
+
+- The `-no-fix` argument turns off the ability to automatically fix lint error code.
+
+## `-modern change`
+
+``` bash
+Usage: modern change [options]
+
+Create a changeset
+
+Options:
+  --empty Create an empty changeset (default: false)
+  --open Open the created changeset in the editor (default: false)
+  -h, --help display help for command
+```
+
+The `modern change` command is used to generate the required Markdown file for [changesets](https://github.com/changesets/changesets).
+
+## `modern pre`
+
+``` bash
+Usage: modern pre [options] <enter|exit> [tag]
+
+Entering and exiting pre-publishing mode
+
+Options:
+  -h, --help display help for command
+```
+
+You can use the `modern pre` command to [pre-release](https://github.com/atlassian/changesets/blob/main/docs/prereleases.md) a version before the official release.
+
+## `modern bump`
+
+``` bash
+Usage: modern bump [options]
+
+Use changesets to automatically update releases and changelogs
+
+Options:
+  --canary Create a pre-release for testing (default: false)
+  --preid <tag> Specify an identifier when versioning a pre-release (default: "next")
+  --snapshot Create a special version for testing (default: false)
+  -h, --help display help for command
+```
+
+Modify the version number in `package.json` according to the Markdown file of the changelog generated by [changesets](https://github.com/changesets/changesets), and generate the `CHANGELOG.md` file.
+
+## `modern release`
+
+``` bash
+Usage: modern release [options]
+
+Release npm packages
+
+Options:
+  --tag <tag> Release npm packages with a specific tag (default: "")
+  --ignore-scripts release ignores the scripts command in package.json, only supported in pnpm monorepo
+                    (default: "")
+  -h, --help display help for command
+```
+
+The `-modern release` command releases the module to the [npm Registry](https://www.npmjs.com/).
+
+- The `-tag` argument specifies the specific [dist tags](https://docs.npmjs.com/adding-dist-tags-to-packages) to be used for the release.
+
+## `modern gen-release-note`
+
+``` bash
+Usage: modern gen-release-note [options]
+
+Generate Release Note based on current repository changeset information
+
+Options:
+  --repo <repo> The name of the repository to generate the Pull Request link, e.g.: modern-js-dev/modern.js
+  --custom <cumtom> Custom Release Note generation function
+  -h, --help display help for command
+```
+
+Automatically generate [Release Note](https://en.wikipedia.org/wiki/Release_notes) based on the changeset information of the current repository.
+
+:::tip{title=Note}
+needs to be executed before the ``bump`` command.
+:::
+
+## `modern upgrade`
+
+``` bash
+Usage: modern upgrade [options]
+
+Upgrade Modern.js to the latest version
+
+Options:
+  --registry <registry> customize npm registry (default: "")
+  -d,--debug Enable Debug mode to print debug log messages (default: false)
+  --cwd <cwd> project path (default: "")
+  -h, --help display help for command
+```
+
+The `modern upgrade` command is used to upgrade the project Modern.js related dependencies to the latest version.
+
+Executing the command `npx modern upgrade` in the project root directory will update the Modern.js dependencies in `package.json` of the currently executing project to the latest version by default.
+
+command is provided in `@modern-js/module-tools` version **>= 1.17.0**, previous versions can be upgraded using `npx @modern-js/upgrade`.

package/docs/en/guide/basic/modify-output-product.md

@@ -0,0 +1,145 @@
+## Modify output product
+
+## Default output products
+
+When the `modern build` command is used in an initialized project, the products are generated according to the default configuration supported by Module Tools. The default supported configurations are as follows.
+
+``` typescript
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset: 'base-config',
+});
+```
+
+**The default generated product has the following characteristics**:
+
+- The code format is [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules), or simply `cjs`.
+- Code syntax is supported up to `ES6`.
+- All code is packaged into a single file, i.e. **bundle** processing is performed.
+- The output root directory is the `dist` directory under the project, and the output directory for type files is `dist/types`.
+
+:::tip
+1. By "code syntax support up to ES6", we mean that the syntax supported by the product code will not exceed `ES6`. If the source code uses syntax above `ES6` (e.g. `ES2017`), it will be converted.
+:::
+
+You may have the following questions when you see this:
+
+1. what is `buildPreset`?
+2. what determines these characteristics of the output?
+
+Then the next step is to first explain `buildPreset`.
+
+## buildPreset
+
+`buildPreset` represents one or more sets of build-related configurations prepared in advance. By using the corresponding preset values of `buildPreset`, you can eliminate the troublesome and complicated configuration work and get the expected product.
+
+### String form of `buildPreset`
+
+The value of a **build preset can be in the form of a string**, so a build preset of this form is called a preset string.
+
+The module engineering solution provides generic build preset strings and corresponding variants, depending on the generic scenario in which the npm package is used. All currently supported preset strings can be viewed via the [BuildPreset API](/en/api/build-config). The relationship between **generic preset strings and variants** is explained here.
+
+Among the generic preset strings, `"npm-library"` can be used in the scenario of developing npm packages of the library type, which is suitable for most common module type projects. When `"npm-library"` is set, the output product of the project will have the following characteristics:
+
+- In the `dist/lib` directory you will get the product in the code format `cjs`, with syntax support up to `es6` and after packaging.
+- In the `dist/es` directory, you get code in the format `esm`, with syntax support up to `es6` and packaged.
+- In the `dist/types` directory, you get the type files. If it is not a TypeScript project, there is no such directory.
+
+The default string `"npm-library"` is a variant of the original product with modified **code-syntax support** and a string naming change to `"npm-library-[es5 | es2016.... . es2020 | esnext]"`.
+
+For example, if the output product is based on the preset string `"npm-library"` and the syntax supported by the product code is changed to `es2017`, then simply changing `"npm-library"` to `"npm-library-es2017"` would be sufficient.
+
+### Function form of `buildPreset`
+
+**In addition to the string form, the value of a build preset can also be in the form of a function, where the specific configuration corresponding to a preset value can be printed or modified**.
+
+For example, if the same effect as the preset string `"npm-library-es2017"` is achieved using the preset function form, it can be done as follows:
+
+``` typescript
+import { defineConfig } from "@modern-js/module-tools";
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset.NPM_LIBRARY.map(config => {
+      return { ... .config, target: 'es2017' }
+    });
+  },
+});
+```
+
+In the above code implementation, `preset.NPM_LIBRARY` corresponds to the preset string `"npm-library"`, which represents the `"npm-library"` equivalent of a multi-group build-related configuration. We traverse the `NPM_LIBRARY` array, which contains multiple `buildConfig` objects, with the `map` method. We make a shallow copy of the original `buildConfig` object and modify the shallow copy to get `buildConfig.target`, specifying it as `es2017`.
+> The specific value of `preset.NPM_LIBRARY` can be viewed via the [BuildPreset API](/en/api/build-config). The `preset` object contains not only `NPM_LIBRARY`, but also other similar constants.
+
+So what is the `buildConfig` object here? And what are the previously mentioned build product features based on?
+
+We explain it next.
+
+## Build configuration (object)
+
+**`buildConfig` is a configuration object that describes how to compile and generate build products**. What was mentioned at the beginning about "*features of build products*" are actually properties supported by `buildConfig`. The currently supported properties cover the needs of most module type projects when building products. `buildConfig` not only contains some of the properties that products have, but also some of the features needed to build products. The following is a brief list from a classification point of view:
+
+**The basic attributes of a build product include:**
+
+- Whether the product is packaged or not: the corresponding API is [`buildConfig.buildType`](/en/api/build-config#buildtype).
+- Product support for syntax: the corresponding API is [`buildConfig.target`](/en/api/build-config#target).
+- Output format: The corresponding API is [`buildConfig.format`](/en/api/build-config#format).
+- How to handle the output type file: the corresponding API is [`buildConfig.dts`](/en/api/build-config#dts).
+- How the sourceMap of the product is handled: the corresponding API is [`buildConfig.sourceMap`](/en/api/build-config#sourcemap).
+- The input (or source file) corresponding to the output: the corresponding API is [`buildConfig.input`](/en/api/build-config#input).
+- The directory of the output of the product: the corresponding API is [`buildConfig.outdir`](/en/api/build-config#outdir).
+- The source directory of the build: the corresponding API is [`buildConfig.sourceDir`](/en/api/build-config#sourcedir).
+
+**Common functions needed to build products include:**
+
+- Alias: The corresponding API is [`buildConfig.alias`](/en/api/build-config#alias).
+- Static resource handling: The corresponding API is [`buildConfig.asset`](/en/api/build-config#asset).
+- Third-party dependency handling: The corresponding APIs are
+  * [`buildConfig.autoExternal`](/en/api/build-config#autoexternal).
+  * [`buildConfig.externals`](/en/api/build-config#externals).
+- Copy: The corresponding API is [`buildConfig.copy`](/en/api/build-config#copy).
+- Global variable substitution: the corresponding API is [`buildConfig.define`](/en/api/build-config#define).
+- Specify [JSX](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) compilation method, the corresponding API is [`buildConfig.jsx`](/en/api/build-config#jsx).
+
+**Some advanced properties or less frequently used functions:**
+
+- Product code compression: The corresponding API is [`buildConfig.minify`](/en/api/build-config#minify).
+- Code splitting: [`buildConfig.splitting`](/en/api/build-config#splitting)
+- Specify whether the build product is for the NodeJS environment or the browser environment: the corresponding API is [`buildConfig.platform`](/en/api/build-config#platform).
+- umd product-related.
+  * Specifies the global variables imported externally to the umd product: the corresponding API is [`buildConfig.umdGlobals`](/en/api/build-config#umdglobals).
+  * Specify the module name of the umd product: the corresponding API is [`buildConfig.umdModuleName`](/en/api/build-config#umdmodulename).
+
+In addition to the above categories, frequently asked questions and best practices about these APIs can be found at the following links.
+
+* [What are `bundle` and `bundleless`?](/en/guide/advance/in-depth-about-build#bundle-and-bundleless)
+* [The relationship between `input` and `sourceDir`](/en/guide/advance/in-depth-about-build#relationship-between-input-and-sourcedir)
+* [The multiple ways of generating type files in products](/en/guide/advance/in-depth-about-build#declaration-type-files)
+* [The use of `buildConfig.define` for different scenarios.](/en/guide/advance/in-depth-about-build#buildconfigdefine-usage-for-different-scenarios)
+* [How to handle third-party dependencies?](/en/guide/advance/external-dependency)
+* [How to use copy?](/en/guide/advance/copy)
+* [How to build umd products?](/en/guide/advance/build-umd)
+* [The capabilities currently supported by static resources.](/en/guide/advance/asset)
+
+## When to use `buildConfig`
+
+`buildConfig` is one of the ways used to modify the product, **and only `buildConfig` will take effect when configured in conjunction with `buildPreset`**. So if configured as follows.
+
+``` typescript
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildConfig: [{}],
+  buildPreset: 'base-config',
+});
+```
+
+Then at this point you will see the following prompt.
+
+``` bash
+Since both 'buildConfig' and 'buildPreset' are present, only the 'buildConfig' configuration will take effect
+```
+
+The set or sets of build-related configurations represented by `buildPreset` are composed of `buildConfig`, **which can be used to customize output products** when the current project needs cannot be met using `buildPreset`.
+
+The process of using `buildConfig` is the process of thinking about "*what kind of build product to get*".

package/docs/en/guide/basic/publish-your-project.md

@@ -0,0 +1,115 @@
+# Versioning and Publishing
+
+An npm-type module project release process consists of two phases.
+
+* The first phase is during development, where the developer needs to provide a change file to record changes that need to be released.
+* The second phase is during release, where Module Tools can collect all the change files to update the version, update the release log, and release new packages to the [npm Registry](https://www.npmjs.com/).
+
+## Tracking changes
+
+**Changes need to be logged when they happen to the project**. Changes that occur in a project are typically.
+
+* New features
+* Fixes to issues
+* Configuration file changes
+* ...
+
+Once these changes have been made, the current changes need to be documented with the following command.
+
+* [`modern change`](/zh/guide/command-preview#modern-change)
+
+Executing the `modern change` command asks the developer several questions and generates a change log based on the developer's answers. The changelog file contains the type of change and its description, and is committed to the git repository.
+
+``` bash
+$ npx modern change
+🦋 What kind of change is this for module-example? (current version is 0.1.0) - patch
+🦋 Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
+🦋 Summary - publish test
+🦋 === Releasing the following packages ===
+🦋 [Patch]
+🦋 module
+🦋 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 /xxxxxx/module/.changeset/brave-dryers-agree.md
+```
+
+When executed successfully, the resulting Markdown file containing the change log is saved in the project's `.changeset` directory. The contents will look like the following.
+
+``` markdown .changeset/brave-dryers-agree.md
+---
+"``module-example'': patch
+---
+
+publish test
+```
+
+## Version update
+
+When the project version needs to be updated, execute the following command.
+
+* [`modern bump`](/zh/guide/command-preview#modern-bump)
+
+Executing `modern bump` will modify the version number in `package.json` based on the contents of the Markdown file in the `.changeset/` directory where the changes were recorded, and generate the `CHANGELOG.md` file. **These Markdown files are also deleted when the version update is complete, so they are "consumed "**.
+
+``` markdown CHANGELOG.md
+# module
+
+## 0.1.1
+### Patch Changes
+
+- publish test
+```
+
+## Publish
+
+To publish a project, you can execute the following command.
+
+* [`modern publish`](/zh/guide/command-preview#modern-release)
+
+The `modern release` command publishes the project to the npm Registry.
+
+The release is the `latest` version, which is also the official version. If you want to change the `dist-tag`, you can specify it with the `modern release --tag` command. For example.
+
+``` bash
+modern release --tag beta
+```
+
+However, if you want to change the version number of the current project to a pre-release as well, you need to use the `modern pre` command.
+
+> `dist-tag` can be understood as: tagging the current release. Generally speaking, the `dist-tag` for the default release is `latest`, so you can consider `latest` as the `dist-tag` for the official release.
+
+## Pre-releases
+
+When a pre-release is needed before the official release, the following command is executed.
+
+* [`modern pre`](/zh/guide/command-preview#modern-pre)
+
+First `modern pre enter <tag>` to enter pre-release mode, `<tag>` can be the same as the `tag` specified with the `modern release --tag` command when releasing the project.
+
+``` bash
+$ npx modern pre enter next
+🦋 success Entered pre mode with tag next
+🦋 info Run `changeset version` to version packages with prerelease versions
+✨ Done in 5.30s.
+Done in 5.30s. ```
+
+Then you can update the specific version number with the `modern bump` command, **which doesn't actually "consume" the Markdown file that records the changes**: ``` bash
+
+``` bash
+$ npx modern bump
+🦋 warn ===============================IMPORTANT!===============================
+🦋 warn You are in prerelease mode
+🦋 warn If you meant to do a normal release you should revert these changes and run `changeset pre exit`
+🦋 warn You can then run `changeset version` again to do a normal release
+🦋 warn ----------------------------------------------------------------------
+🦋 All files have been updated. review them and commit at your leisure
+```
+
+Then you can see that the updated version number in `package.json` will look like this: `0.1.2-next.0`.
+
+Finally, **if you don't need to do a pre-release anymore, be sure to run the `modern pre exit` command** to exit the pre-release state and to release the official version when you run the `modern bump` command again.
+
+
+Translated with www.DeepL.com/Translator (free version)

package/docs/en/guide/basic/test-your-project.mdx

@@ -0,0 +1,158 @@
+# Testing Projects
+
+This chapter will describe how to test modules.
+
+## Prerequisites and conventions
+
+To use the testing functionality of the project, you need to make sure that the project contains the following dependencies:
+
+* `"@modern-js/plugin-testing"`
+
+In the module engineering scheme, the following conventions are in place for test cases, or files for writing tests:
+
+* The `tests` directory in the project directory is the directory for test cases and test files, **no support for changing the directory for running test cases**.
+* Files with the suffix `.test.[tj]sx?` are automatically recognized as test files by default.
+* Other `. [tj]sx?` suffixes are recognized as normal files that can be used as test `utils` files or for other purposes.
+
+
+## Run the tests
+
+Once the dependencies are prepared and we know where to write the test cases, we can execute the tests with the following command:
+
+``` bash
+modern test
+
+// Update snapshot
+modern test --updateSnapshot
+```
+
+After execution, you will see the results of the test:
+
+![test-result](/test-result.png)
+
+## Usage Configuration
+
+The Module Engineering Program provides the following configurations for testing.
+
+* [`testing`](/zh/api/config-test)
+
+You can add it in `modern.config.(j|t)s`.
+
+## Test example
+
+### Common modules
+
+For common modules, we can use the test function as follows:
+
+<CH.Spotlight>
+
+``` typescript ./src/index.ts
+export default function () {
+  return 'hello world';
+}
+```
+
+---
+
+First is the code of the module.
+
+``` typescript ./src/index.ts
+export default function () {
+  return 'hello world';
+}
+```
+
+---
+
+Then in the test file, we can do this.
+
+Where `@` points to the source directory, defined in `tests/tsconfig.json` in the initialization project.
+
+``` typescript ./tests/index.test.ts
+import main from '@/index';
+
+describe('default cases', () => {
+  test('Have returns', () => {
+    const drink = jest.fn(main);
+    drink();
+    expect(drink).toHaveReturned();
+  });
+});
+```
+
+---
+
+Finally we can execute `modern test`.
+
+``` bash
+pnpm test
+## or
+yarn test
+## or
+npm run test
+```
+
+</CH.Spotlight>
+
+### Components
+
+For components, Modern.js's [Runtime API](xxx) provides functionality for testing UI components, which is provided by `@modern-js/runtime/testing`.
+
+:::tip
+If you need to use the Runtime API, then you can turn it on via [microgenerator](/zh/guide/command-preview).
+:::
+
+<CH.Spotlight>
+
+``` tsx ./src/index.tsx
+export const default () {
+  return (
+    <div>This is a UI Component</div>
+  );
+}
+```
+
+---
+
+First is the code of the component.
+
+``` tsx ./src/index.tsx
+export const default () {
+  return (
+    <div>This is a UI Component</div>
+  );
+}
+```
+
+---
+
+Then in the test file, we can do this.
+
+Where `@` points to the source directory, defined in `tests/tsconfig.json` in the initialization project.
+
+``` tsx ./tests/index.test.tsx
+import { render, screen } from '@modern-js/runtime/testing';
+
+import Component from '@/index';
+
+describe('default cases', () => {
+  test('Rendered', () => {
+    render(<Component />);
+    expect(screen.getByText('This is a UI Component')).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+Finally we can execute `modern test`.
+
+``` bash
+pnpm test
+## or
+yarn test
+## or
+npm run test
+```
+
+</CH.Spotlight>

package/docs/en/guide/basic/use-micro-generator.md

@@ -0,0 +1,35 @@
+# Using the Microgenerator
+
+The Module Engineering solution provides the Microgenerator tool, which allows for the current project to.
+
+* add new directories and files
+* Modify the contents of the `package.json` file
+* Execute commands
+
+Thus with these capabilities, **Microgenerator can enable additional feature functionality for the project**.
+
+The microgenerator can be started via [`modern new`](/zh/guide/command-preview). The current Microgenerator features supported by the Module Engineering program are:
+
+## Storybook
+
+The **Storybook feature** can be enabled when we want to debug a component or a common module. When this feature is enabled, **the `stories` directory and related files are created in the project directory, and a new `"@modern-js/plugin-storybook"` dependency is added to package.json**.
+
+For more information on how to start Storybook and how to use it, check out the following link.
+
+* [`modern dev`](/en/guide/command-preview#modern-dev)
+* [using Storybook](xxx)
+
+## Tailwind CSS support
+
+This can be enabled when we want to add [Tailwind CSS](https://v2.tailwindcss.com/) support to our project. Tailwind CSS is a CSS library that provides out-of-the-box styling.
+
+For more information on how to use Tailwind CSS in your module projects, check out.
+
+* [Using Tailwind CSS](xxx)
+
+
+## Modern.js Runtime API
+
+**Modern.js provides [Runtime API](xxx) capabilities that can only be used in the Modern.js application project environment**. If you need to develop a component for use in a Modern.js application environment, then you can turn on this feature and the microgenerator will add the `"@modern-js/runtime"` dependency.
+
+Also, the Storybook debugging tool will determine if the project needs to use the Runtime API by checking the project's dependencies and providing the same Runtime API runtime environment as the Modern.js application project.