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

package/docs/en/guide/basic/using-storybook.mdx

@@ -0,0 +1,187 @@
+# Using Storybook
+
+First of all, if you haven't read the following, take a few minutes to understand it first.
+
+* [use micro-generator to enable Storybook debugging](/en/guide/use-micro-generator#storybook-debug)
+* [`modern dev`](/en/guide/command-preview#modern-dev)
+
+[Storybook](https://storybook.js.org/) is a tool dedicated to component debugging, providing around component development.
+
+* Develop UIs that are more durable
+* Test UIs with less effort and no flakes
+* Document UI for your team to reuse
+* Share how the UI actually works
+* Automate UI workflows
+
+So it is a complex and powerful tool.
+
+The modular engineering solution is integrated with Storybook, so you can pretty much follow the official Storybook documentation. However, there are still a few things to keep in mind, which are explained below.
+
+## Debugging code
+
+Component code needs to be introduced during debugging code, and currently component code can be introduced in two ways:
+
+* Referencing the component product
+* Referencing component source code
+
+We recommend the first way of "**referencing component product**". Because it is almost close to the real usage scenario, not only can we debug the component functionality, but also verify the correctness of the build product.
+
+Next, we will talk about how to use each of these two methods.
+
+### Referencing component products
+
+If the TypeScript project `foo` exists.
+
+<CH.Spotlight>
+
+```json package.json
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./dist/types/index.d.ts"
+}
+```
+
+---
+
+Make sure the `main` and `types` of `package.json`
+values are real paths.
+
+```json package.json
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./dist/types/index.d.ts"
+}
+```
+
+---
+
+The source code of the `foo` project.
+
+```typescript src/index.ts
+export const content = 'hello world';
+```
+
+---
+
+
+Make sure that the `paths` configuration pointing to the project root is set in `stories/tsconfig.json`.
+The `key` of `paths` is the same as the project name.
+
+```json stories/tsconfig.json focus=7:9
+{
+  "extends": "../tsconfig.json",
+  "include": ["./"],
+  "compilerOptions": {
+    "jsx": "preserve",
+    "baseUrl": ".",
+    "paths": {
+      "foo": ["../"]
+    }
+  }
+}
+```
+
+---
+
+Finally, it is referenced directly in the Story code by the project name.
+
+```tsx stories/index.stories.tsx focus=1:1
+import { content } from 'foo';
+
+const Component = () => <div>this is a Story Component {content}</div>;
+
+export const YourStory = () => <Component />;
+
+export default {
+  title: 'Your Stories',
+};
+```
+
+</CH.Spotlight>
+
+If, during development, you encounter a situation where the type definition is not available in real time, at that point.
+
+For `pnpm` projects, `package.json` can be modified as follows.
+
+``` ts focus=4:7
+{
+    "name": "foo",
+    "main": "./dist/index.js",
+    "types": "./src/index.ts",
+    "publishConfig": {
+      "types": "./dist/index.d.ts",
+    }
+}
+```
+> For the use of pnpm's `publishConfig`, you can read the following [link](https://pnpm.io/package_json#publishconfig).
+
+For npm and Yarn projects, the values of `types` of `package.json` can only be changed manually in **development phase** and **release phase**.
+
+
+So why is it possible to reference the product directly?
+
+1. the `modern build` command is executed automatically before the `modern dev storybook` command, ensuring the existence of the project build product.
+2. The project name is added as an alias inside Storybook to ensure that the path to the project's product can be parsed **according to `package.json`**.
+
+
+### Referencing component source code
+
+Referencing component source code can be done by means of relative paths to:
+
+```ts ./stories/index.tsx
+import { content } from '../src';
+
+const Component = () => <div>this is a Story Component {content}</div>;
+
+export const YourStory = () => <Component />;
+
+export default {
+  title: 'Your Stories',
+};
+```
+
+So why is the source code approach not recommended?
+
+Not only is it impossible to verify that the component product is correct using the component source code, **but also some of the configurations supported by the module project for building the product cannot be fully translated into Storybook internal configuration**. If some of the configurations cannot be converted to each other, there will be unintended results during Storybook debugging.
+
+
+## Configure Storybook
+
+### Configuration file
+
+Storybook is officially configured for projects through a folder called `.storybook`, which contains various configuration files. **In a module project scenario, Storybook configuration files can be added to the `config/storybook` directory of the project.**
+
+For more information on how to use the various Storybook configuration files, see the following links:
+
+* [Configure Storybook](https://storybook.js.org/docs/react/configure/overview)
+
+**But there are some limitations to Storybooking in a module project**:
+
+* It is currently not possible to change the location of the Story file, i.e., you cannot change the `stories` configuration in the `main.js` file.
+* Currently you cannot modify Webpack and Babel related configuration, i.e. you cannot modify `webpackFinal` and `babel` configuration in the `main.js` file.
+
+In the future we will consider whether these configurations can be allowed to be modified, but for now we are limiting their use to reduce unpredictable issues.
+
+### `dev.storybook`
+
+In addition to the configuration file, the module engineering solution also provides a `dev.storybook` configuration item in the `modern.config.(j|t)s` project configuration file.
+
+The webpack configuration of Storybook can be modified via this configuration.
+
+* [`dev.storybook.webpack`](xxx)
+
+### Building Storybook Products
+
+In addition to Storybook debugging of components or common modules, you can also perform Storybook build tasks with the following commands.
+
+``` bash
+modern build --platform storybook
+```
+
+For the `modern build --platform` command you can see.
+
+* [`modern build`](/en/guide/command-preview#modern-build)
+
+After the build is complete, you can see the build product files in the `dist/storybook-static` directory.

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

@@ -0,0 +1,78 @@
+# Quick start
+
+## 3 minute demo
+
+Want to experience Module Tools in action? The only prerequisite you need is [Node.js LTS](https://github.com/nodejs/Release) and make sure your Node version is **>= 14.17.6**.
+
+From your shell, install the following dependencies in your project.
+
+- `@modern-js/module-tools`
+- `@modern-js/plugin-testing`
+
+> If it's a TypeScript project, add the `"typescript"` dependency.
+
+```bash
+npm install -D @modern-js/module-tools @modern-js/plugin-testing
+```
+
+> For projects that use pnpm or the Yarn package manager, just replace npm. **pnpm is recommended**.
+
+Then add the command `"build": "modern build"` to your project's `package.json` file.
+
+```json
+{
+    "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
+
+## Execute the build.
+pnpm build
+
+## Execute the build in listening mode.
+pnpm build --watch
+
+## Start Storybook
+pnpm dev storybook
+
+## Test
+pnpm test
+pnpm test
+```
+
+**If you want to create a complete module project, you can execute the following command:**
+
+```bash
+npx @modern-js/create your-project-dir-name
+```
+
+Next, in the issue interaction, follow the options below.
+
+```bash
+? Please select the type of project you want to create Module
+? Please fill in the project name library
+? 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.
+
+We can start the project build directly with the `pnpm build` command, and start the build in watching mode with the `pnpm build --watch` command.
+
+## Let's get started
+
+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

@@ -0,0 +1,14 @@
+# 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.
+
+If you are planning to develop a project of the npm package type, then you came to the right place! Modern.js provides a professional module engineering solution. It gives you:
+
+- **Simple project initialization**: simply execute the `npx @modern-js/create project-dir` command, followed by a few interactive questions, to create a complete module type project. The created project also supports the choice of two package managers, [**pnpm**](https://pnpm.io/) and [**Yarn**](https://classic.yarnpkg.com/).
+- **Code formatting**: In a module project, you can execute `modern lint` to format the code. The initialized module project includes the [ESLint](https://eslint.org/docs/latest/user-guide/core-concepts#what-is-eslint) ruleset for Modern.js for most scenarios.
+- **Comprehensive build capabilities and faster builds**: Module Tools provides high-performance build capabilities based on [esbuild](https://esbuild.github.io/getting-started/) and [SWC](https://swc.rs/), and provides rich configurations for different build scenarios.
+- **Storybook debugging tools**: Module Tools provides [Storybook](https://storybook.js.org/) debugging tools for debugging module projects. After installing the Storybook plugin for Module Tools, you can start it with the `modern dev storybook` command. You can use Storybook not only for debugging components, but also for other types of modules.
+- **Testing capabilities with Jest**: When you need to test a module, you can use the `modern test` command of Module Tools, which not only integrates with [Jest](https://jestjs.io/), but also provides an API for configuring [Jest](https://jestjs.io/docs/configuration).
+- **Versioning based on Changesets**: When you need to record changes to a project, you can use the `modern change` command to generate a Markdown file containing the changes; when you need to upgrade a project, you can use the `modern bump` command to analyze and upgrade the version through the Markdown file; when you need to release a project, you can use the `modern release` command to release the project; Module Tools implements these commands based on [Changesets](https://github.com/changesets/changesets).
+- **Extensible plug-in mechanism**: Want to integrate additional debugging tools for your project? Or maybe you want to do some extra processing during the build process, Module Tools provides a plugin mechanism and plugin hooks that cover both the `dev` command and the `build` command process. You can use them to extend the capabilities of your project.
+- **Lots more!** Module Tools will continue to optimize its build and debug features in the future. If there are important issues to be solved in module project building, or if a mainstream module project debugging tool or pattern emerges, then they will probably be supported by Module Tools.

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

@@ -0,0 +1,17 @@
+# 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.
+
+For example, when we consider which builder is used to build the code for a module project, we might previously consider [webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/guide/en/), but now we might also consider [esbuild](https://esbuild.github.io/) or [SWC](https://swc.rs/).
+
+Regardless of which builder is chosen, this is going to be a costly learning curve for developers who are not skilled in the use of these build tools. Even if you want to use them quickly, it will take a lot of time and effort.
+
+In addition to the build, things like providing debugging tools for projects, supporting testing capabilities, adding code format validation, etc. can take a long time and effort for a novice to understand or master them and actually serve the current project.
+
+To ensure the quality of the code and the integrity of the project, we often need to do these things that are not related to the logical implementation of the code. However, these things are likely to affect the overall project development progress, reduce the developer's development experience, and make the developer feel that the development threshold of the module project is very high.
+
+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)
+
+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

@@ -0,0 +1,35 @@
+---
+pageType: home
+
+hero:
+  name: Module tools
+  text: 模块工程解决方案
+  tagline: 简单、强大、高性能的现代化npm包开发方案
+  image:
+    src: /island.png
+    alt: Island
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /zh/guide/getting-started
+
+features:
+  - title: 'Libuild: 现代库构建方案'
+    details: 基于 Libuild 构建，构建速度极快，带给你极致的开发体验。
+    icon: 🚀
+  - title: 'Storybook: 社区流行的UI开发工具'
+    details: 集成了Storybook，你可以使用它调试UI。
+    icon: 📦
+  - title: 'Island: 强大的现代化SSG方案'
+    details: 高性能的静态站点生成器。
+    icon: 🔑
+  - title: 'transform + bundle'
+    details: 支持bundle和bundleless两种构建模式。
+    icon: ✨
+  - title: '零配置'
+    details: 无需任何配置即可开发你的npm包，内置预设覆盖多种场景。
+    icon: 🛠️
+  - title: '扩展性强: 提供强大的插件机制'
+    details: 通过其插件扩展机制，你可以轻松的扩展Module tools的各项能力。
+    icon: 🎨
+---