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

package/docs/en/guide/advance/in-depth-about-build.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # In-depth understanding of build
 
 In the [Basic Usage] section, we already knew that you can modify the output product of a project through the `buildConfig` configuration. `buildConfig` not only describes some of the features of the product, but also provides some functionality for building the product.
@@ -5,8 +9,8 @@ In the [Basic Usage] section, we already knew that you can modify the output pro
 :::tip{title=notes}
 If you are not sure what `buildConfig` is, it is recommended to take some time to understand it by following this link.
 
-* [[modify-output-product](/en/guide/modify-output-product)]
-:::
+- [[modify-output-product](/en/guide/basic/modify-output-product)]
+  :::
 
 In this chapter we'll dive into the use of certain build configurations and understand what happens when the `modern build` command is executed.
 
@@ -20,15 +24,15 @@ A Bundle is a package of build products, which may be a single file or multiple
 
 Bundleless, on the other hand, means that each source file is compiled and built separately, but not packaged together. Each product file can be found with its corresponding source code file. The process of **Bundleless build can also be understood as the process of code conversion of source files only**.
 
-In `buildConfig` you can specify whether the current build task is Bundle or Bundleless by using [`buildConfig.buildType`](/en/api/build-config#buildtype).
+In `buildConfig` you can specify whether the current build task is Bundle or Bundleless by using [`buildConfig.buildType`](/en/api/config/build-config#buildtype).
 
 ### Relationship between `input` and `sourceDir`
 
-[`buildConfig.input`](/en/api/build-config#input) is used to specify the file path or directory path where the source code is read, and its default value differs between Bundle and Bundleless builds.
+[`buildConfig.input`](/en/api/config/build-config#input) is used to specify the file path or directory path where the source code is read, and its default value differs between Bundle and Bundleless builds.
 
-* When `buildType: 'bundle'`, `input` defaults to `['src/index.ts']`
-* When `buildType: 'bundleless'`, `input` defaults to `['src']`
-> In fact, at `buildType: 'bundle'`, the build tool detects the existence of a file matching the name rule `src/index.(j|t)sx?` and uses it as an entry file.
+- When `buildType: 'bundle'`, `input` defaults to `['src/index.ts']`
+- When `buildType: 'bundleless'`, `input` defaults to `['src']`
+  > In fact, at `buildType: 'bundle'`, the build tool detects the existence of a file matching the name rule `src/index.(j|t)sx?` and uses it as an entry file.
 
 :::warn{title=notes}
 It is recommended that you do not specify multiple source file directories during a Bundleless build, as unintended results may occur. Bundleless builds with multiple source directories are currently in an unstable stage.
@@ -40,16 +44,16 @@ We know from the defaults: **Bundle builds can generally specify a file path as
 
 In addition to setting `input` to an array, you can also set it to an object during the Bundle build process. **By using the object form, we can modify the name of the file that the build product outputs**. So for the following example, `. /src/index.ts` corresponds to the path of the build product file as `. /dist/main.js`.
 
-``` tsx modern.config.ts
+```tsx modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
-    buildConfig: {
-        input: {
-            main: ['./src/index.ts'],
-        },
-        outdir: './dist',
+  buildConfig: {
+    input: {
+      main: ['./src/index.ts'],
     },
+    outDir: './dist',
+  },
 });
 ```
 
@@ -57,19 +61,19 @@ The Bundleless build process also supports such use, but it is not recommended.
 
 #### `sourceDir`
 
-[`sourceDir`](/en/api/build-config#sourcedir) is used to specify the source code directory, which is related to both.
+[`sourceDir`](/en/api/config/build-config#sourcedir) is used to specify the source code directory, which is related to both.
 
-* type file generation
-* [`outbase`](https://esbuild.github.io/api/#outbase) for specifying the build process
+- type file generation
+- [`outbase`](https://esbuild.github.io/api/#outbase) for specifying the build process
 
 In general:
 
-* **During the Bundleless build process, the values of `sourceDir` and `input` should be the same, and their default values are both `src`**.
-* It is rarely necessary to use `sourceDir` during the Bundle build process.
+- **During the Bundleless build process, the values of `sourceDir` and `input` should be the same, and their default values are both `src`**.
+- It is rarely necessary to use `sourceDir` during the Bundle build process.
 
 ### Declaration Type Files
 
-The [`buildConfig.dts`](/en/api/build-config#dts) configuration is mainly used for type file generation.
+The [`buildConfig.dts`](/en/api/config/build-config#dts) configuration is mainly used for type file generation.
 
 #### Turn off type generation
 
@@ -80,8 +84,8 @@ import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   buildConfig: {
-    dts: false
-  }
+    dts: false,
+  },
 });
 ```
 
@@ -95,8 +99,8 @@ With `buildType: 'bundleless'`, type files are generated using the project's `ts
 
 The **module engineering solution also supports packaging of type files**, although care needs to be taken when using this feature.
 
-* Some third-party dependencies have incorrect syntax that can cause the packaging process to fail. So in this case, you need to exclude such third-party packages manually with [`buildConfig.externals`](/en/api/build-config#externals).
-* It is not possible to handle the case where the type file of a third-party dependency points to a `.ts` file. For example, the `package.json` of a third-party dependency contains something like this: `{"types": ". /src/index.ts"}`.
+- Some third-party dependencies have incorrect syntax that can cause the packaging process to fail. So in this case, you need to exclude such third-party packages manually with [`buildConfig.externals`](/en/api/config/build-config#externals).
+- It is not possible to handle the case where the type file of a third-party dependency points to a `.ts` file. For example, the `package.json` of a third-party dependency contains something like this: `{"types": ". /src/index.ts"}`.
 
 #### Alias Conversion
 
@@ -108,18 +112,18 @@ import utils from '@common/utils';
 
 Normally, product type files generated with `tsc` will also contain these aliases. However, Module Tools will convert the aliases in the type file generated by `tsc` to:
 
-* Alias conversion is possible for code of the form `import '@common/utils'` or `import utils from '@common/utils'`.
-* Aliasing is possible for code of the form `export { utils } from '@common/utils'`.
+- Alias conversion is possible for code of the form `import '@common/utils'` or `import utils from '@common/utils'`.
+- Aliasing is possible for code of the form `export { utils } from '@common/utils'`.
 
 However, there are some cases that cannot be handled at this time.
 
-* Output types of the form `Promise<import('@common/utils')>` cannot be converted at this time.
+- Output types of the form `Promise<import('@common/utils')>` cannot be converted at this time.
 
 #### Some examples of the use of `dts`
 
 General usage:
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -130,13 +134,14 @@ export default defineConfig({
       tsconfigPath: './other-tsconfig.json',
       distPath: './types',
     },
-    outdir: './dist',
-  }
+    outDir: './dist',
+  },
 });
 ```
+
 For the use of `dts.only`:
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
@@ -145,33 +150,33 @@ export default defineConfig({
     {
       buildType: 'bundle',
       dts: false,
-      outdir: './dist',
+      outDir: './dist',
     },
     {
       buildType: 'bundleless',
       dts: {
         only: true,
       },
-      outdir: './dist/types',
-    }
-  ]
+      outDir: './dist/types',
+    },
+  ],
 });
 ```
 
 ### `buildConfig.define` Usage for different scenarios
 
-[`buildConfig.define`](/en/api/build-config#define) functions somewhat similar to [`webpack.DefinePlugin`](https://webpack.js.org/plugins/define-plugin/). A few usage scenarios are described here.
+[`buildConfig.define`](/en/api/config/build-config#define) functions somewhat similar to [`webpack.DefinePlugin`](https://webpack.js.org/plugins/define-plugin/). A few usage scenarios are described here.
 
 #### Environment variable replacement
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
     define: {
-      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0')
-    }
-  }
+      'process.env.VERSION': JSON.stringify(process.env.VERSION || '0.0.0'),
+    },
+  },
 });
 ```
 
@@ -182,7 +187,7 @@ With the above configuration, we can put the following code.
 console.log(process.env.VERSION);
 ```
 
-When executing ``VERSION=1.0.0 modern build``, the conversion is:
+When executing `VERSION=1.0.0 modern build`, the conversion is:
 
 ```
 // compiled code
@@ -191,14 +196,14 @@ console.log('1.0.0');
 
 #### Global variable replacement
 
-``` ts
+```ts
 import { defineConfig } from '@modern-js/module-tools';
 export default defineConfig({
   buildConfig: {
     define: {
-      'VERSION': JSON.stringify(require('. /package.json').version || '0.0.0')
-    }
-  }
+      VERSION: JSON.stringify(require('. /package.json').version || '0.0.0'),
+    },
+  },
 });
 ```
 
@@ -217,9 +222,10 @@ console.log('1.0.0');
 ```
 
 Note, however: If the project is a TypeScript project, then you may need to add the following to the `.d.ts` file in the project source directory.
+
 > If the `.d.ts` file does not exist, then you can create it manually.
 
-``` ts env.d.ts
+```ts env.d.ts
 declare const YOUR_ADD_GLOBAL_VAR;
 ```
 
@@ -227,10 +233,10 @@ declare const YOUR_ADD_GLOBAL_VAR;
 
 When the `modern build` command is executed, the
 
-* Clear the products directory according to `buildConfig.outdir`.
-* Compile `js/ts` source code to generate the JS build product for Bundle/Bundleless.
-* Generate Bundle/Bundleless type files using `tsc`.
-* Handle Copy tasks.
+- Clear the products directory according to `buildConfig.outDir`.
+- Compile `js/ts` source code to generate the JS build product for Bundle/Bundleless.
+- Generate Bundle/Bundleless type files using `tsc`.
+- Handle Copy tasks.
 
 ## Build errors
 
@@ -238,7 +244,7 @@ When a build error occurs, based on the information learned above, it is easy to
 
 **Errors reported for js or ts builds:**
 
-``` bash
+```bash
 error  ModuleBuildError:
 
 ╭───────────────────────╮
@@ -252,7 +258,7 @@ Detailed Information:
 
 **Errors reported for the type file generation process:**
 
-``` bash
+```bash
 error   ModuleBuildError:
 
 bundle DTS failed:
@@ -260,7 +266,7 @@ bundle DTS failed:
 
 For `js/ts` build errors, we can tell from the error message.
 
-* By `'bundle failed:'` to determine if the error is reported for a Bundle build or a Bundleless build?
-* What is the `format` of the build process?
-* What is the `target` of the build process?
-* The specific error message.
+- By `'bundle failed:'` to determine if the error is reported for a Bundle build or a Bundleless build?
+- What is the `format` of the build process?
+- What is the `target` of the build process?
+- The specific error message.

package/docs/en/guide/advance/in-depth-about-dev-command.md

@@ -1,12 +1,16 @@
-# 深入理解构建
+---
+sidebar_position: 2
+---
+
+# 深入理解 dev 命令
 
 在【基础使用】的部分，我们已经知道可以通过 `buildConfig` 配置对项目的输出产物进行修改。`buildConfig` 不仅描述了产物的一些特性，同时还为构建产物提供了一些功能。
 
 :::tip{title=注意}
 如果你还不清楚 `buildConfig` 是什么，建议花一些时间通过下面的链接了解一下：
 
-* 【[修改输出产物](/zh/guide/modify-output-product)】
-:::
+- 【[修改输出产物](/guide/basic/modify-output-product)】
+  :::
 
 而在本章里我们将要深入理解某些构建配置的使用以及了解执行 `modern build` 命令的时候发生了什么。
 
@@ -19,4 +23,3 @@
 ### input 与 sourceDir 的关系
 
 ## 构建过程
-

package/docs/en/guide/advance/theme-config.mdx

@@ -0,0 +1,80 @@
+---
+sidebar_position: 7
+---
+
+# Theme Configuration
+
+The module project provides the ability to configure themes through the [`designSystem`](/en/api/config/design-system) API.
+
+## Motivation and rationale
+
+Theme configuration is somewhat similar to the custom theme functionality in the component library and is mainly used in style development. We can use the `designToken` generated by the `designSystem` configuration in different style development environments.
+
+The so-called `designToken` corresponds to different things in different style development environments.
+
+- tailwindcss: use `designSystem` as the `theme` configuration for tailwindcss. So you can use.
+  - The name of the HTML class supported by tailwindcss.
+  - `@apply` custom directive under css/less/sass to use a string with the same name as the HTML class name supported by tailwindcss.
+- css/less/scss: Generate global style variables via `designSystem`.
+
+The data structure of the `designSystem` API is borrowed from the [theme API](https://tailwindcss.com/docs/theme) in the `tailwindcss` configuration object, so a default set of `designToken` exists. For the default values, see the [`designSystem` API](/api/config/design-system).
+
+:::info
+The css/less/sass global variables are not supported yet.
+:::
+
+## Usage examples
+
+### tailwindcss
+
+When using tailwindcss, its [`theme`](https://v2.tailwindcss.com/docs/theme#extending-the-default-theme) configuration can be set via `designSystem`.
+
+For example, the following configuration extends the original color configuration:
+
+```ts ./modern.config.ts
+export default {
+  designSystem: {
+    extend: {
+      colors: {
+        primary: '#1677ff',
+      },
+    },
+  },
+};
+```
+
+We can have two ways of using tailwindcss in our code.
+
+#### HTML Class
+
+```tsx ./src/index.tsx
+import 'tailwindcss/utilities.css';
+
+export default () => {
+  return <div className="bg-primary"></div>;
+};
+```
+
+#### `@apply` Directives
+
+:::info
+About [`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply)。
+:::
+
+<CH.Code>
+
+```tsx ./src/index.tsx
+import './index.css';
+
+export default () => {
+  return <div className="btn-primary"></div>;
+};
+```
+
+```css ./src/index.css
+.btn-primary {
+  @apply bg-primary;
+}
+```
+
+</CH.Code>

package/docs/en/guide/basic/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Basic Guide",
+  "sidebar_position": 2
+}

package/docs/en/guide/basic/before-getting-started.md

@@ -1,21 +1,26 @@
+---
+sidebar_position: 1
+---
+
 # Before you start
 
 ## Environment preparation
 
 In order to use the Modern.js module engineering solution, you first need [NodeJS](https://nodejs.org/zh/) engine, we recommend the latest [LTS version](https://github.com/nodejs/Release), and make sure the Node version is **>=14.17.6**. because non-stable NodeJS releases frequently have bugs. You might consider installing via [nvm-windows](https://github.com/coreybutler/nvm-windows) and [nvm](https://github.com/nvm-sh/nvm) (Mac/linux), so you can easily switch to different NodeJS versions that might be required for different projects that you work on.
+
 ## Getting Started with npm
 
 Once NodeJS is installed, not only can you access the `node` executable from the command line, but you can also execute the `npm` command.
 
 Npm is the standard package manager for NodeJS. It started out as a tool for downloading and managing NodeJS package dependencies, but it has since evolved into a tool for front-end JavaScript.
 
-**If you already know something about usage of npm and npm packages, then you can directly see [npm package manager](/en/guide/before-getting-started#npm-package-manager) section.**
+**If you already know something about usage of npm and npm packages, then you can directly see [npm package manager](/en/guide/basic/before-getting-started#npm-package-manager) section.**
 
 ## npm package type project
 
-So what is an npm package type project? When we execute the `npm init` command in an empty project directory, it creates a JSON file with the file name `package.json` under the current directory. During the creation process, we will need to fill in information including but not limited to the *name*, *version* *number*, *description*, etc. of the npm package, which will be found in the resulting `package.json` file as follows
+So what is an npm package type project? When we execute the `npm init` command in an empty project directory, it creates a JSON file with the file name `package.json` under the current directory. During the creation process, we will need to fill in information including but not limited to the _name_, _version_ _number_, _description_, etc. of the npm package, which will be found in the resulting `package.json` file as follows
 
-``` json
+```json
 {
   "name": "npm-demo",
   "version": "1.0.0",
@@ -41,27 +46,27 @@ When adding a third-party npm package to an initial project, we can call this pr
 
 - `"dependencies"`: a type of package that your application will need in a production environment.
 - `"devDependencies"`: another type of package that is only needed for local development and testing.
-> packages can be understood as third-party npm packages.
+  > packages can be understood as third-party npm packages.
 
 You can install the packages you need in a **production environment** by running `npm install npm-package-name` or `npm add npm-package-name`, or you can manually write the packages you need to install and the corresponding [semantic version](https://docs.npmjs.com/about-semantic-versioning) in `"dependencies"` in the `package.json` file, and run the `npm install` command to.
 
-``` json
+```json
 {
-    "name": "your-npm-project",
-    "dependencies": {
-      "npm-package-name": "0.1.0"
-    },
+  "name": "your-npm-project",
+  "dependencies": {
+    "npm-package-name": "0.1.0"
+  }
 }
 ```
 
 Similarly, you can install **only packages needed for local development and testing** by running `npm install npm-package-name --save-dev` or `npm add npm-package-name --save-dev`, or you can manually write the packages to be installed and the corresponding [semantic version](https://docs.npmjs.com/about-semantic-versioning) in `"devDependencies"` in the `package.json` file, and run the `npm install` command as follows
 
-``` json
+```json
 {
-    "name": "your-npm-project",
-    "devDependencies": {
-      "npm-package-name": "0.1.0"
-    },
+  "name": "your-npm-project",
+  "devDependencies": {
+    "npm-package-name": "0.1.0"
+  }
 }
 ```
 
@@ -92,13 +97,13 @@ These can be executed by running `npm run-script <stage>` or simply `npm run <st
 
 Name matching [pre and post commands](https://docs.npmjs.com/cli/v9/using-npm/scripts#pre--post-scripts) will also be run (e.g. `premyscript`, `myscript`, `postmyscript` ).
 
-``` json
+```json
 {
-    "scripts": {
-        "premyscript": "",
-        "myscript": "",
-        "postmyscript": "",
-    }
+  "scripts": {
+    "premyscript": "",
+    "myscript": "",
+    "postmyscript": ""
+  }
 }
 ```
 
@@ -160,14 +165,14 @@ A configuration file for Module Tools is provided in the initial module project
 
 The contents of the initial configuration file are as follows.
 
-``` typescript
+```typescript
 // modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({});
 ```
 
-``` js
+```js
 // modern.config.js
 const { defineConfig } = require('@modern-js/module-tools');
 
@@ -176,12 +181,12 @@ module.exports = defineConfig({});
 
 **We recommend using the `defineConfig` function**, but it is not mandatory to use it. So you can also return an object directly in the configuration file: the:
 
-``` typescript
+```typescript
 // modern.config.ts
 export default {};
 ```
 
-``` js
+```js
 // modern.config.js
 module.exports = {};
 ```

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

@@ -1,10 +1,14 @@
+---
+sidebar_position: 2
+---
+
 # Command Preview
 
 Commands available for module engineering projects.
 
 ## `modern build`
 
-``` bash
+```bash
 Usage: modern build [options]
 
 Build module command
@@ -22,7 +26,7 @@ Options:
 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).
+- 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`](/api/config/build-config) configurations in [`dts.tsconfigPath`](/api/config/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.
 
@@ -34,7 +38,7 @@ When executing a Storybook build, it needs to read the project's build product.
 
 ## `modern new`
 
-``` bash
+```bash
 Usage: modern new [options]
 
 Execute the generator in a modular project scenario
@@ -55,11 +59,11 @@ The following features can currently be enabled.
 - 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.
+You can learn more about these features in the [Using the micro generator](/guide/basic/use-micro-generator) section.
 
 ## `modern dev`
 
-``` bash
+```bash
 Usage: modern dev [options]
 
 Local development commands
@@ -71,24 +75,24 @@ 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 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
+```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.
 
+The `modern test` command will automatically run the `src/tests/*.test.(js|ts|jsx|tsx)` file as a test case.
 
 ## `modern lint`
 
-``` bash
+```bash
 Usage: modern lint [options] [. .files]
 
 lint and fix source files
@@ -104,7 +108,7 @@ Run [ESLint](https://eslint.org/) to check the syntax of the code. Usually, we o
 
 ## `-modern change`
 
-``` bash
+```bash
 Usage: modern change [options]
 
 Create a changeset
@@ -119,7 +123,7 @@ The `modern change` command is used to generate the required Markdown file for [
 
 ## `modern pre`
 
-``` bash
+```bash
 Usage: modern pre [options] <enter|exit> [tag]
 
 Entering and exiting pre-publishing mode
@@ -132,7 +136,7 @@ You can use the `modern pre` command to [pre-release](https://github.com/atlassi
 
 ## `modern bump`
 
-``` bash
+```bash
 Usage: modern bump [options]
 
 Use changesets to automatically update releases and changelogs
@@ -148,7 +152,7 @@ Modify the version number in `package.json` according to the Markdown file of th
 
 ## `modern release`
 
-``` bash
+```bash
 Usage: modern release [options]
 
 Release npm packages
@@ -166,7 +170,7 @@ The `-modern release` command releases the module to the [npm Registry](https://
 
 ## `modern gen-release-note`
 
-``` bash
+```bash
 Usage: modern gen-release-note [options]
 
 Generate Release Note based on current repository changeset information
@@ -180,12 +184,12 @@ Options:
 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.
+needs to be executed before the `bump` command.
 :::
 
 ## `modern upgrade`
 
-``` bash
+```bash
 Usage: modern upgrade [options]
 
 Upgrade Modern.js to the latest version