@modern-js/module-tools-docs 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @modern-js/module-tools-docs
+
+## 2.8.0
+
+### Patch Changes
+
+- f4614692f8: feat: add new module plugins
+  feat: 添加新的 Module 插件
+  - @modern-js/doc-plugin-auto-sidebar@2.8.0
+  - @modern-js/doc-tools@2.8.0

package/README.md

@@ -19,8 +19,8 @@ Please follow [Quick Start](https://modernjs.dev/module-tools/en/guide/intro/get
 
 ## Contributing
 
-Please read the [Contributing Guide](https://github.com/modern-js-dev/modern.js/blob/main/CONTRIBUTING.md).
+Please read the [Contributing Guide](https://github.com/web-infra-dev/modern.js/blob/main/CONTRIBUTING.md).
 
 ## License
 
-Modern.js is [MIT licensed](https://github.com/modern-js-dev/modern.js/blob/main/LICENSE).
+Modern.js is [MIT licensed](https://github.com/web-infra-dev/modern.js/blob/main/LICENSE).

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

@@ -178,7 +178,7 @@ 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
+  --repo <repo> The name of the repository to generate the Pull Request link, e.g.: web-infra-dev/modern.js
   --custom <cumtom> Custom Release Note generation function
   -h, --help display help for command
 ```

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

@@ -46,7 +46,7 @@ If your project has a `src/index.(js|jsx)` file or both `src/index.(ts|tsx)` and
 **If you want to see the complete project using the modular engineering scheme, you can execute the following command**.
 
 ```bash
-git clone https://github.com/modern-js-dev/module-tools-examples
+git clone https://github.com/web-infra-dev/module-tools-examples
 cd module-tools-example/base
 
 ## Execute the build.

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

@@ -2,5 +2,7 @@
 
 ## Official Plugin
 
-(Under Building)
+* [@modern-js/plugin-module-import](./plugin-import.md)：Use SWC to provide the same ability as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
+* [@modern-js/plugin-module-banner](./plugin-banner.md)：Add custom content, such as copyright information, to the top and bottom of each JS and CSS file.
+
 

package/docs/en/plugins/official-list/plugin-banner.md

@@ -0,0 +1,103 @@
+# Banner Plugin
+
+Provide the ability to inject content at the top and bottom of each JS and CSS file.
+
+## Quick Start
+
+### Install
+
+```bash
+# npm
+npm install @modern-js/plugin-module-banner -D
+
+# yarn
+yarn add @modern-js/plugin-module-banner -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-banner -D
+```
+
+
+### Register
+
+You can install the plugin with the following command:
+
+```ts
+import moduleTools, defineConfig from '@modern-js/module-tools';
+import pluginBanner from '@modern-js/plugin-module-banner';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    pluginBanner({
+      banner: {
+        js: '//comment',
+        css: '/*comment*/',
+      },
+    }),
+  ],
+});
+```
+
+:::tip
+Note: CSS comments do not support the `//comment` syntax. Refer to [【CSS Comments】](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
+:::
+
+## Example
+
+### Add copyright information at the top of a JS file
+
+```ts
+import pluginBanner from '@modern-js/plugin-module-banner';
+
+const copyRight = `/*
+ © Copyright 2020 xxx.com or one of its affiliates.
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+*/`;
+
+export default defineConfig({
+  plugins: [
+    pluginBanner({
+      banner: {
+        js: copyRight,
+      },
+    }),
+  ],
+});
+```
+
+## Configuration
+
+* **Type:**
+
+```ts
+type BannerOptions = {
+  banner: {
+    js?: string;
+    css?: string;
+  };
+  footer?: {
+    js?: string;
+    css?: string;
+  };
+};
+```
+
+### banner
+
+Add content at the top.
+
+* `banner.js`: Add content at the top of a JS file.
+* `banner.css`: Add content at the top of a CSS file.
+
+### footer
+
+Add content at the bottom.
+
+* `footer.js`: Add content at the bottom of a JS file.
+* `footer.css`: Add content at the bottom of a CSS file.

package/docs/en/plugins/official-list/plugin-import.mdx

@@ -0,0 +1,177 @@
+# Import Plugin
+
+Using [SWC](https://swc.rs/) provides the same ability and configuration as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
+
+## Quick Start
+
+### Install
+
+```bash
+# npm
+npm install @modern-js/plugin-module-import -D
+
+# yarn
+yarn add @modern-js/plugin-module-import -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-import -D
+```
+
+### Register
+
+In Module Tools, you can register plugins in the following way:
+
+```ts
+import moduleTools, defineConfig from '@modern-js/module-tools';
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'antd',
+        style: true,
+      }],
+    }),
+  ],
+});
+```
+
+This way we can use the ability of automatic import in Module Tools.
+
+## Configurations
+
+* **Type**:
+
+```ts
+type Options = {
+  pluginImport?: ImportItem[];
+}
+```
+
+### pluginImport
+
+* **Type**: `Array`
+
+The elements of the array are configuration objects for `babel-plugin-import`, which can be referred to [options](https://github.com/umijs/babel-plugin-import#options)。
+
+**Example:**
+
+```ts
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [
+        // babel-plugin-import`s options config
+        {
+          libraryName: 'foo',
+          style: true,
+        }
+      ],
+    }),
+  ],
+});
+```
+
+## Notes
+
+[SWC](https://swc.rs/) (Speedy Web Compiler) is written in Rust, and this plugin is based on SWC and ported from [babel-plugin-import](https://github.com/umijs/babel-plugin-import). The configuration options remain consistent.
+
+Some configurations can accept functions, such as `customName`, `customStyleName`, etc. These JavaScript functions are called by Rust through Node-API, which can cause some performance degradation.
+
+Simple function logic can be replaced by template language. Therefore, for configurations such as `customName`, `customStyleName`, etc., instead of passing functions, you can also pass a string as a template to replace the function, improving performance.
+
+<CH.Spotlight>
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+---
+
+We will use this piece of code for illustration.
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+---
+
+Add the following configuration on the right-hand side:
+
+
+```ts
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}'
+      }],
+    }),
+  ],
+});
+```
+
+---
+
+The `{{ member }}` in it will be replaced with the corresponding import member.
+
+```ts focus=8:8
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}'
+      }],
+    }),
+  ],
+});
+```
+
+
+---
+After transformation:
+
+```ts
+import Btn from 'foo/es/MyButton';
+```
+
+</CH.Spotlight>
+
+
+Template `customName: 'foo/es/{{ member }}'` is the same as `` customName: (member) => `foo/es/${member}` ``, but template value has no performance overhead of Node-API.
+
+The template used here is [handlebars](https://handlebarsjs.com). There are some useful builtin tools, Take the above import statement as an example:
+
+
+```ts focus=8:8
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ kebabCase member }}',
+      }],
+    }),
+  ],
+});
+```
+
+Transformed to:
+
+```ts
+import Btn from 'foo/es/my-button';
+```
+
+In addition to kebabCase, there are cameraCase, snakeCase, upperCase and lowerCase can be used as well.

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

@@ -178,7 +178,7 @@ Usage: modern gen-release-note [options]
 根据当前仓库 changeset 信息生成 Release Note
 
 Options:
-  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： modern-js-dev/modern.js
+  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： web-infra-dev/modern.js
   --custom <cumtom>  自定义 Release Note 生成函数
   -h, --help         display help for command
 ```

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

@@ -63,7 +63,7 @@ export default defineConfig({
 
 关于如何在模块工程里使用 Tailwind CSS，可以查看：
 
-- [使用 Tailwind CSS](https://modernjs.dev/docs/apis/module/config/tools/tailwindcss)
+- [使用 Tailwind CSS](https://modernjs.dev/module-tools/guide/best-practices/components.html#tailwind-css)
 
 :::tip
 在成功开启后，会提示需要手动在配置中增加如下类似的代码。
@@ -82,7 +82,7 @@ export default defineConfig({
 
 ## 启动 Modern.js Runtime API
 
-**Modern.js 提供了 [Runtime API](https://modernjs.dev/docs/apis/module/runtime/) 能力，这些 API 只能在 Modern.js 的应用项目环境中使用**。如果你需要开发一个 Modern.js 应用环境中使用的组件，那么你可以开启该特性，微生成器会增加 `"@modern-js/runtime"`依赖。
+**Modern.js 提供了 [Runtime API](https://modernjs.dev/configure/app/runtime/intro) 能力，这些 API 只能在 Modern.js 的应用项目环境中使用**。如果你需要开发一个 Modern.js 应用环境中使用的组件，那么你可以开启该特性，微生成器会增加 `"@modern-js/runtime"`依赖。
 
 另外，Storybook 调试工具也会通过检测项目的依赖确定项目是否需要使用 Runtime API，并且提供与 Modern.js 应用项目一样的 Runtime API 运行环境。
 

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

@@ -44,7 +44,7 @@ export default defineConfig({
 **如果你想要看看使用了模块工程方案的完整项目，可以执行以下命令**：
 
 ```bash
-git clone https://github.com/modern-js-dev/module-tools-examples
+git clone https://github.com/web-infra-dev/module-tools-examples
 cd module-tools-example/base
 
 ## 执行构建：

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

@@ -2,4 +2,5 @@
 
 ## 官方插件
 
-（建设中）
+* [@modern-js/plugin-module-import](./plugin-import.md)：使用 SWC 提供与 `babel-plugin-import` 一样的能力。
+* [@modern-js/plugin-module-banner](./plugin-banner.md)：为每个 JS 和 CSS 文件的顶部和底部添加自定义内容，例如版权信息。

package/docs/zh/plugins/official-list/plugin-banner.md

@@ -0,0 +1,103 @@
+# Banner 插件
+
+提供为每个 JS 和 CSS 文件的顶部和底部注入内容的能力。
+
+## 快速开始
+
+### 安装
+
+```bash
+# npm
+npm install @modern-js/plugin-module-banner -D
+
+# yarn
+yarn add @modern-js/plugin-module-banner -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-banner -D
+```
+
+
+### 注册插件
+
+在 Module Tools 中，你可以按照如下方式注册插件：
+
+```ts
+import moduleTools, defineConfig from '@modern-js/module-tools';
+import pluginBanner from '@modern-js/plugin-module-banner';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    pluginBanner({
+      banner: {
+        js: '//comment',
+        css: '/*comment*/',
+      },
+    }),
+  ],
+});
+```
+
+:::tip
+注意：CSS 的注释不支持 `//comment` 这样的写法。详见[【CSS 注释】](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Comments)
+:::
+
+## 示例
+
+### 在 JS 文件顶部增加版权信息
+
+```ts
+import pluginBanner from '@modern-js/plugin-module-banner';
+
+const copyRight = `/*
+ © Copyright 2020 xxx.com or one of its affiliates.
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+*/`;
+
+export default defineConfig({
+  plugins: [
+    pluginBanner({
+      banner: {
+        js: copyRight,
+      },
+    }),
+  ],
+});
+```
+
+## 配置
+
+* 类型：
+
+```ts
+type BannerOptions = {
+  banner: {
+    js?: string;
+    css?: string;
+  };
+  footer?: {
+    js?: string;
+    css?: string;
+  };
+};
+```
+
+### banner
+
+在顶部增加内容。
+
+* `banner.js`：在 JS 文件顶部增加内容。
+* `banner.css`：在 CSS 文件顶部增加内容。
+
+### footer
+
+在底部增加内容。
+
+* `footer.js`：在 JS 文件底部增加内容。
+* `footer.css`：在 CSS 文件底部增加内容。

package/docs/zh/plugins/official-list/plugin-import.mdx

@@ -0,0 +1,176 @@
+# Import 插件
+
+提供与 [babel-plugin-import](https://github.com/umijs/babel-plugin-import) 等价的能力和配置，基于 [SWC](https://swc.rs/) 实现。
+
+## 快速开始
+
+### 安装
+
+```bash
+# npm
+npm install @modern-js/plugin-module-import -D
+
+# yarn
+yarn add @modern-js/plugin-module-import -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-import -D
+```
+
+### 注册插件
+
+在 Module Tools 中，你可以按照如下方式注册插件：
+
+```ts
+import moduleTools, defineConfig from '@modern-js/module-tools';
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'antd',
+        style: true,
+      }],
+    }),
+  ],
+});
+```
+
+这样我们就可以在 Module Tools 中使用自动导入的能力了。
+
+## 配置
+
+* 类型：
+
+```ts
+type Options = {
+  pluginImport?: ImportItem[];
+}
+```
+
+### pluginImport
+
+* 类型：`Array`
+
+其中数组元素为一个 babel-plugin-import 的配置对象。配置对象可以参考 [options](https://github.com/umijs/babel-plugin-import#options)。
+
+使用示例：
+
+```ts
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [
+        // babel-plugin-import 的 options 配置
+        {
+          libraryName: 'foo',
+          style: true,
+        }
+      ],
+    }),
+  ],
+});
+```
+
+## 注意事项
+
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 Rust 语言编写的，而该插件是基于 SWC，移植自 [babel-plugin-import](https://github.com/umijs/babel-plugin-import)，配置选项保持了一致。
+
+一些配置可以传入函数，例如 `customName`，`customStyleName` 等，这些 JavaScript 函数会由 Rust 通过 Node-API 调用，这种调用会造成一些性能劣化。
+
+简单的函数逻辑其实可以通过模版语言来代替，因此 `customName`，`customStyleName` 等这些配置除了可以传入函数，也可以传入字符串作为模版来代替函数，提高性能。
+
+<CH.Spotlight>
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+---
+
+我们以这段代码进行说明。
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+---
+
+添加右侧的配置：
+
+
+```ts
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}'
+      }],
+    }),
+  ],
+});
+```
+
+---
+
+其中的 `{{ member }}` 会被替换为相应的引入成员
+
+```ts focus=8:8
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}'
+      }],
+    }),
+  ],
+});
+```
+
+
+---
+转换后:
+
+```ts
+import Btn from 'foo/es/MyButton';
+```
+
+</CH.Spotlight>
+
+
+可以看出配置 `customName: "foo/es/{{ member }}"` 的效果等同于配置 `` customName: (member) => `foo/es/${member}`  `` ，但是不会有 Node-API 的调用开销。
+
+这里使用到的模版是 [handlebars](https://handlebarsjs.com)，模版配置中还内置了一些有用的辅助工具，还是以上面的导入语句为例，配置成：
+
+```ts focus=8:8
+import moduleImport from '@modern-js/plugin-module-import';
+
+export default defineConfig({
+  plugins: [
+    moduleImport({
+      pluginImport: [{
+        libraryName: 'foo',
+        customName: 'foo/es/{{ kebabCase member }}',
+      }],
+    }),
+  ],
+});
+```
+
+会转换成下面的结果：
+
+```ts
+import Btn from 'foo/es/my-button';
+```
+
+除了 `kebabCase` 以外还有 `camelCase`，`snakeCase`，`upperCase`，`lowerCase` 可以使用。

package/modern.config.ts

@@ -38,11 +38,11 @@ function getNavbar(lang: 'zh' | 'en'): NavItem[] {
       items: [
         {
           text: getText('更新日志', 'Changelog'),
-          link: 'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
+          link: 'https://github.com/web-infra-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
         },
         {
           text: getText('贡献指南', 'Contributing'),
-          link: 'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
+          link: 'https://github.com/web-infra-dev/modern.js/tree/main/packages/solutions/module-tools/CHANGELOG.md',
         },
       ],
     },
@@ -91,7 +91,7 @@ export default defineConfig({
           icon: 'github',
           mode: 'link',
           content:
-            'https://github.com/modern-js-dev/modern.js/tree/main/packages/solutions/module-tools',
+            'https://github.com/web-infra-dev/modern.js/tree/main/packages/solutions/module-tools',
         },
       ],
       locales: [

package/package.json

@@ -2,18 +2,18 @@
   "name": "@modern-js/module-tools-docs",
   "description": "Shared documentation of Modern.js Module Tools",
   "homepage": "https://modernjs.dev/module-tools",
-  "bugs": "https://github.com/modern-js-dev/modern.js/issues",
-  "repository": "modern-js-dev/modern.js",
+  "bugs": "https://github.com/web-infra-dev/modern.js/issues",
+  "repository": "web-infra-dev/modern.js",
   "license": "MIT",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "main": "index.js",
   "dependencies": {
     "@code-hike/mdx": "^0.7.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "shiki": "^0.11.1",
-    "@modern-js/doc-tools": "2.7.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.7.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.8.0",
+    "@modern-js/doc-tools": "2.8.0"
   },
   "scripts": {
     "dev": "modern dev",