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

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

@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "sidebar_position": 1
+}

package/docs/en/guide/intro/getting-started.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 3
+---
+
 # Quick start
 
 ## 3 minute demo
@@ -21,15 +25,16 @@ Then add the command `"build": "modern build"` to your project's `package.json`
 
 ```json
 {
-    "scripts": {
-        "build": "modern build"
-    }
+  "scripts": {
+    "build": "modern build"
+  }
 }
 ```
 
 If your project has a `src/index.(js|jsx)` file or both `src/index.(ts|tsx)` and `tsconfig.json` files, then congratulations you can run the `npm run build` command directly to build your project with Module Tools.
 
 **If you want to see real projects that use the module engineering solution, you can execute the following command**.
+
 ```bash
 git clone https://github.com/modern-js-dev/module-tools-examples
 cd module-tools-example
@@ -62,6 +67,7 @@ Next, in the issue interaction, follow the options below.
 ? Please select the development language TS
 ? Please select the package management tool pnpm
 ```
+
 > The project name is the value of the `"name"` field in `package.json`.
 
 Then the process of initializing the project will start. After the project directory and files are generated and the dependencies are installed, a complete module project is created.
@@ -75,4 +81,3 @@ Choose your tutorial scenario...
 - I'm a beginner and need to learn [basic usage](/en/guide/before-getting-started) of Module Tools.
 - I have learned the basic usage of Module Tools and can learn [advanced usage](/en/guide/before-getting-started) of Module Tools.
 - I am the maintainer of the project and need to learn how to develop plugins for Module Tools and learn more about Module Tools Advanced.
-

package/docs/en/guide/intro/welcome.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # Welcome to Module Tools
 
 Module Tools is a modules engineering solution for Modern.js, as well as a core dependency. It allows developers to build, debug, and publish module type project more easily. A module type project can mostly be thought of as an npm package type project, which may be a component, component library or tool library project.

package/docs/en/guide/intro/why-module-engineering-solution.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 2
+---
+
 # Why module project solution
 
 You've probably all experienced it: when developing a component library or tool library from scratch, we have to consider not only how to write the code logic of the project itself, but also how to build, debug, test, format the code, and other things that have nothing to do with the code logic.
@@ -12,6 +16,6 @@ To ensure the quality of the code and the integrity of the project, we often nee
 
 If you have to go through all this work every time you develop a module type project, you will spend most of your development time in the beginning on these things that are not related to code implementation. If we could provide a module engineering solution that would help developers to solve the project engineering issues and allow them to focus more on code implementation, it would greatly improve the module type project development experience.
 
-![Not using engineering solution vs. using engineering solution](/why-module-solution.png)
+![Not using engineering solution vs. using engineering solution](https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/module-tools/why-module-solution.png)
 
 Modern.js, in order to make developing module type projects easier, provides a module engineering solution in order to solve the above mentioned problems and provides the main features using Module Tools. **Module-tools can be understood as a tool dedicated to the development of module type projects**.

package/docs/en/index.md

@@ -2,16 +2,13 @@
 pageType: home
 
 hero:
-  name: Module tools
+  name: Modern.js Module
   text: 模块工程解决方案
   tagline: 简单、强大、高性能的现代化npm包开发方案
-  image:
-    src: /island.png
-    alt: Island
   actions:
     - theme: brand
       text: 快速开始
-      link: /zh/guide/getting-started
+      link: /guide/getting-started
 
 features:
   - title: 'Libuild: 现代库构建方案'
@@ -33,3 +30,4 @@ features:
     details: 通过其插件扩展机制，你可以轻松的扩展Module tools的各项能力。
     icon: 🎨
 ---
+# index

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

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

package/docs/en/plugins/guide/getting-started.mdx

@@ -0,0 +1,84 @@
+---
+sidebar_position: 1
+---
+
+# Quick Start
+
+Module engineering solution not only provides a rich set of features, but also supports extending the capabilities of the current project by way of plugins.
+
+We can quickly see how to write a module-tools plugin by using the following example.
+
+<CH.Spotlight>
+
+```md . /project
+. /project .
+├── plugins
+│ └── example.ts
+├── src/
+└── modern.config.ts
+```
+
+---
+
+First we create `. /plugins/example.ts` file under the initialized project.
+
+```md . /project
+
+```
+
+---
+
+Next add the code for the plugin to the `example.ts` file.
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+export const ExamplePlugin = (): CliPlugin<ModuleTools> => {
+  return {
+    name: 'example',
+    setup() {
+      console.info('this is example plugin');
+      return {
+        // use hooks
+        afterBuild() {
+          console.info('build over');
+        }
+      };
+    };
+  };
+};
+```
+
+---
+
+Then we register the plugin we just wrote via the [`plugins`](/en/api/plugins) API.
+
+```ts . /modern.config.ts
+import { ExamplePlugin } from '. /plugins/example';
+export default defineConfig({
+  plugins: [ExamplePlugin()],
+});
+```
+
+---
+
+Finally, run `modern build` and you will see.
+
+```bash terminal
+This is example plugin
+Build succeed: 510.684ms
+build over
+```
+
+</CH.Spotlight>
+
+With the above example, we learned the following things.
+
+- The recommended plugin directory structure
+- The initialization code of the plugin
+- Plugin registration
+
+In addition to the above, we also need to understand.
+
+- [plugin objects, type definitions and recommended configuration items](/en/plugins/guide/plugin-object)
+- [setup functions, `api` object parameters, lifecycle hooks](/en/plugins/guide/setup-functions)

package/docs/en/plugins/guide/plugin-object.mdx

@@ -0,0 +1,85 @@
+---
+sidebar_position: 2
+---
+
+# Plugin Object
+
+The module-tools plugin is an object, and the object contains the following properties.
+
+- `name`: The name of the plugin, a unique identifier.
+- `setup`: plugin initialization function, which will be executed only once. setup function can return a [Hooks object](), and module-tools will execute the function corresponding to the Hook defined on the Hooks object at a specific time.
+
+For example, in the following plugin code example, the `beforeBuild` function is triggered before the project starts the build task and the `build start` log is printed.
+
+<CH.Code>
+
+```ts . /plugins/demo.tsx
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+const MyPlugin: CliPlugin<ModuleTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    return {
+      // this is hook
+      beforeBuild: () => {
+        console.info('build start');
+      },
+    };
+  },
+};
+```
+
+---
+
+```ts . /modern.config.ts
+import { MyPlugin } from '. /plugins/demo';
+export default {
+  plugins: [MyPlugin()],
+};
+```
+
+</CH.Code>
+
+## Plugin type definitions
+
+When using TypeScript, you can introduce the built-in `CliPlugin` and `ModuleTools` types to provide the correct type derivation for plugins: ``
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+const MyPlugin: CliPlugin<ModuleTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    const foo = '1';
+
+    return {
+      // this is hook
+      afterBuild: () => {
+        //...
+      },
+    };
+  },
+};
+```
+
+## Plugin configuration items
+
+**It is recommended to write the plugin as a function**, so that the plugin can receive configuration items via function entry.
+
+```ts
+import type { CliPlugin, ModuleTools } from '@modern-js/module-tools';
+
+type MyPluginOptions = {
+  foo: string;
+};
+
+const MyPlugin = (options: MyPluginOptions): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  setup() {
+    console.log(options.foo);
+  },
+});
+```

package/docs/en/plugins/guide/setup-function.mdx

@@ -0,0 +1,117 @@
+---
+sidebar_position: 3
+---
+
+# Setup function
+
+In the [[Plugin object]](/zh/plugins/guide/plugin-object) section we know that the plug-in object contains a `setup` function that not only contains an `api` object parameter, but also returns a Hooks object.
+
+## Plugin API objects
+
+The `setup` function of the plugin will provide an `api` object parameter, and you can call some of the methods provided on this object to get information about the configuration, project context, etc.
+
+```ts
+export default (): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    // Get the original configuration of the application
+    const config = api.useConfigContext();
+    // Get the application runtime context
+    const appContext = api.useAppContext();
+    // Get the final configuration after resolving
+    const resolvedConfig = api.useResolvedConfigContext();
+  },
+});
+```
+
+### `api.useAppContext`
+
+Used to get project context information.
+
+```ts
+const useAppContext: () => IAppContext;
+
+interface IAppContext {
+  appDirectory: string;
+  configFile: string | false;
+  packageName: string;
+  nodeModulesDirectory: string;
+  internalDirectory: string;
+  plugins: {
+    cli?: any;
+    server?: any;
+  }[];
+}
+```
+
+:::info
+We can see through the actual type file that there are other fields, but the only ones that make sense for the module project at the moment are the above. api object other methods are the same.
+:::
+
+### `api.useResolvedConfigContext`
+
+Used to get the final configuration after parsing.
+
+:::info
+If you need to get the build-related final configuration, you need to use the [`beforeBuild`]() Hook.
+:::
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig;
+
+interface NormalizedConfig {
+  buildConfig: PartialBuildConfig;
+  buildPreset: BuildPreset;
+  designSystem?: Record<string, any>;
+  dev: Dev;
+  plugins: PluginConfig;
+  runtime: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+  _raw: UserConfig;
+}
+```
+
+### `api.useHookRunners`
+
+Used to get the executors of Hooks and trigger the execution of a specific Hook.
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    const hookRunners = api.useHookRunners();
+    // trigger the afterBuild Hook
+    await hookRunners.afterBuild();
+  },
+});
+```
+
+## Asynchronous setup
+
+The setup of a CLI plugin can be an asynchronous function that performs asynchronous logic during the initialization process.
+
+```ts
+export default (): CliPlugin<ModuleTools> => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    await doSomething();
+  },
+});
+```
+
+## Life cycle hooks
+
+We know that the `setup` function returns a Hooks object, which can also be understood as an object with module-tools lifecycle hooks.
+
+Currently there are two main types of hooks.
+
+- build hooks: triggered only when the `build` command is executed to build the source code product.
+- `buildPlatform` hook: triggered only when the `build --platform` command is executed to generate other build products.
+- debug hooks: hooks that are triggered when running the `dev` command.
+
+See the [API documentation](/en/api/plugin-hooks) for a full list of lifecycle hooks.

package/docs/en/plugins/official-list/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Plugins List",
+  "sidebar_position": 2
+}

package/docs/en/plugins/official-list/overview.md

@@ -0,0 +1,6 @@
+# Overview
+
+## Official Plugin
+
+(Under Building)
+

package/docs/zh/api/config/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "配置项",
+  "sidebar_position": 1
+}