@modern-js/module-tools-docs 2.4.0 → 2.5.0

package/LICENSE

@@ -19,126 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-
-The code implementation modified from external library  are:
-
-- vite
-
-    MIT License
-
-    Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-
-- wmr
-
-    MIT License
-
-    Copyright (c) 2020 The Preact Authors
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-
-- bundle-require
-
-    The MIT License (MIT)
-
-    Copyright © 2021 EGOIST (https://github.com/sponsors/egoist)
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE
-
-- react-dev-utils
-
-    MIT License
-
-    Copyright (c) 2013-present, Facebook, Inc.
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
-
-- jest-cli
-
-    MIT License
-
-    Copyright (c) Facebook, Inc. and its affiliates.
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+<p align="center">
+  <a href="https://modernjs.dev" target="blank"><img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ylaelkeh7nuhfnuhf/modernjs-cover.png" width="300" alt="Modern.js Logo" /></a>
+</p>
+
+<h1 align="center">Modern.js Module Tools</h1>
+
+<p align="center">
+  Simple, powerful, high-performance modern npm package development solution.
+</p>
+
+## Getting Started
+
+Please follow [Quick Start](https://modernjs.dev/module-tools/en/guide/intro/getting-started.html) to get started with Modern.js Module Tools.
+
+## Documentation
+
+- [English Documentation](https://modernjs.dev/module-tools/en)
+- [中文文档](https://modernjs.dev/module-tools/)
+
+## Contributing
+
+Please read the [Contributing Guide](https://github.com/modern-js-dev/modern.js/blob/main/CONTRIBUTING.md).
+
+## License
+
+Modern.js is [MIT licensed](https://github.com/modern-js-dev/modern.js/blob/main/LICENSE).

package/docs/en/api/config/build-config.md

@@ -285,6 +285,44 @@ Generates code for the node environment by default, you can also specify `browse
 - type: `'browser' | 'node'`
 - default: `node`
 
+## sideEffects
+
+Module sideEffects
+
+- Type: `RegExg[] | (filePath: string, isExternal: boolean) => boolean | boolean`
+- Default value: `undefined`
+
+Normally, we configure the module's side effects via the sideEffects field in package.json, but in some cases, such as when we reference a three-party package style file
+
+```js
+import 'other-package/dist/index.css'
+```
+
+But the package.json of this three-party package does not have the style file configured in the sideEffects
+
+```json other-package/package.json
+{
+  "sideEffects": ["dist/index.js"]
+}
+```
+
+This is the time to use this configuration item, which supports regular and functional forms
+
+```js modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    sideEffects: [/\.css$/],
+    // or
+    // sideEffects: (filePath, isExternal) => /\.css$/.test(filePath),
+  },
+});
+```
+
+:::tip
+After adding this configuration, the sideEffects field in package.json will no longer be read when packaging
+:::
+
 ## sourceDir
 
 Specify the source directory of the build, default is `src`, which is used to generate the corresponding product directory based on the source directory structure when building `bundleless`.

package/docs/en/guide/advance/external-dependency.mdx

@@ -71,18 +71,9 @@ console.info(React);
 
 </CH.Spotlight>
 
-## Packaging third-party dependencies
-
-However there are cases where you want to package these third-party dependencies into the product. The benefits of packaging third-party dependencies into the product are: **Reducing the time spent downloading third-party dependencies**.
-
-This way of handling third-party dependencies is generally more common in developing command-line tools, which can improve the loading speed of command-line tools and give users a better experience.
+If you want to modify the default processing, you can use the following API.
 
-So how do you enable the packaging of third-party dependencies in your module project?
-
-The following APIs are provided in the build configuration to handle third-party dependencies:
-
-- [`buildConfig.autoExternal`](/en/api/config/build-config#autoexternal)
-- [`buildConfig.externals`](/en/api/config/build-config#externals)
+- [`buildConfig.autoExternal`](/api/config/build-config#autoexternal)
 
 ### Turn off default behavior
 
@@ -110,9 +101,61 @@ export default defineConfig({
 });
 ```
 
+## Packaging third-party dependencies
+
+However there are cases where you want to package these third-party dependencies into the product. The benefits of packaging third-party dependencies into the product are:**Less time spent downloading third-party dependencies**. This way of handling third-party dependencies is generally more common in developing command-line tools, which can improve the loading speed of command-line tools and give users a better experience.
+
+So how do you enable the packaging of third-party dependencies in the module project?
+
+**When we want to package certain dependencies, we generally declare them in `"devDependencies"` in package.json**. In this case, the dependencies declared in `"devDependencies"` are **allowed** to be packaged in the product during the build process.
+
+<CH.Spotlight>
+
+```json ./v1/package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+If the project needs to package `react` dependencies.
+
+```json ./v1/package.json
+```
+
+---
+
+When a `react` dependency is used in the source code.
+
+```tsx src/index.ts
+import React from 'react';
+console.info(React);
+```
+
+---
+
+The `react` code will be packaged into the product at this point.
+
+```js dist/index.js
+// ...
+var import_react = __toESM(require_react());
+function src_default() {
+  console.info(import_react.default);
+}
+```
+
+</CH.Spotlight>
+
+However, in a real build scenario, you may encounter a third-party dependency that cannot be handled, so you can use the following API to **external** them.
+
+- [`buildConfig.externals`](/en/api/config/build-config#externals)
+
 ### Exclude specified third-party dependencies
 
-And in addition to the `buildConfig.autoExternal` API, `buildConfig.externals` can also control which third-party dependencies are to be handled. We can combine these two
+We mentioned above the use of the `buildConfig.autoExternal` API, while `buildConfig.externals` can also control which third-party dependencies to handle. So we can combine these two
 APIs to handle the project's dependencies in a more granular way.
 
 For example, when we need to leave only certain dependencies unpacked, we can configure it as follows.

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

@@ -68,6 +68,10 @@ pnpm test
 npx @modern-js/create your-project-dir-name
 ```
 
+:::info
+Execute `npx @modern-js/create -h` for more command line arguments
+:::
+
 Next, in the issue interaction, follow the options below.
 
 ```bash
@@ -88,5 +92,5 @@ We can start the project build directly with the `pnpm build` command, and start
 Choose your tutorial scenario...
 
 - I'm a beginner and need to learn [basic usage](/en/guide/basic/before-getting-started) of Module Tools.
-- I have learned the basic usage of Module Tools and can learn [advanced usage](/en/guide/basic/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.
+- I have learned the basic usage of Module Tools and can learn [advanced usage](/en/guide/advance/in-depth-about-build) of Module Tools.
+- I need to expand my project capabilities and need to learn how to develop [plugins](/en/plugins/guide/getting-started) for Module Tools.

package/docs/zh/api/config/build-config.md

@@ -342,6 +342,44 @@ export default defineConfig({
 - 类型： `'browser' | 'node'`
 - 默认值： `node`
 
+## sideEffects
+
+配置模块的副作用
+
+- 类型： `RegExg[] | (filePath: string, isExternal: boolean) => boolean | boolean`
+- 默认值： `undefined`
+
+通常情况下，我们通过 package.json 的 `"sideEffects"` 字段来配置模块的副作用，但是在某些情况下，例如我们引用了一个三方包的样式文件。
+
+```js
+import 'other-package/dist/index.css'
+```
+
+但是这个三方包的 package.json 里并没有将样式文件配置到 `"sideEffects"` 里。
+
+```json other-package/package.json
+{
+  "sideEffects": ["dist/index.js"]
+}
+```
+
+这时候就可以使用这个配置项，支持正则和函数形式。
+
+```js modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  buildConfig: {
+    sideEffects: [/\.css$/],
+    // or
+    // sideEffects: (filePath, isExternal) => /\.css$/.test(filePath),
+  },
+});
+```
+
+:::tip
+添加此配置后，打包时将不会再读取 package.json 里的 `"sideEffects"` 字段。
+:::
+
 ## sourceDir
 
 指定构建的源码目录,默认为 `src`，用于在 `bundleless` 构建时基于源码目录结构生成对应的产物目录。
@@ -619,7 +657,7 @@ const tailwind = {
 - 类型： `Record<string, string>`
 - 默认值： `{}`
 
-```js modern.config.ts
+```ts modern.config.ts
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({

package/docs/zh/guide/advance/external-dependency.mdx

@@ -71,18 +71,10 @@ console.info(React);
 
 </CH.Spotlight>
 
-## 打包第三方依赖
-
-不过也有一些情况希望将这些第三方依赖打包到产物。将第三方依赖打包到产物的好处是：**减少下载第三方依赖所花费的时间**。
-
-这种处理第三方依赖的方式一般在开发命令行工具中比较常见，这可以提升命令行工具的加载速度，给使用者带来更好的使用体验。
 
-那么如何在模块工程中开启对于第三方依赖的打包处理呢？
-
-在构建配置中提供了以下 API 来处理第三方依赖：
+如果想要修改默认的处理方式，可以通过下面的 API 进行修改：
 
 - [`buildConfig.autoExternal`](/api/config/build-config#autoexternal)
-- [`buildConfig.externals`](/api/config/build-config#externals)
 
 ### 关闭默认行为
 
@@ -110,9 +102,61 @@ export default defineConfig({
 });
 ```
 
+## 打包第三方依赖
+
+不过也有一些情况希望将这些第三方依赖打包到产物。将第三方依赖打包到产物的好处是：**减少下载第三方依赖所花费的时间**。这种处理第三方依赖的方式一般在开发命令行工具中比较常见，这可以提升命令行工具的加载速度，给使用者带来更好的使用体验。
+
+那么如何在模块工程中开启对于第三方依赖的打包处理呢？
+
+**当希望打包某些依赖的时候，一般来说会将这些依赖声明在 package.json 的 `"devDependencies"` 中**。此时在构建过程中，会**允许**声明在 `"devDependencies"` 中的依赖打包到产物中。
+
+<CH.Spotlight>
+
+```json ./v1/package.json
+{
+  "devDependencies": {
+    "react": "^17"
+  }
+}
+```
+
+---
+
+如果项目需要打包 `react` 依赖。
+
+```json ./v1/package.json
+```
+
+---
+
+当源码中使用了 `react` 依赖。
+
+```tsx src/index.ts
+import React from 'react';
+console.info(React);
+```
+
+---
+
+此时产物中会将 `react` 代码打包到产物中。
+
+```js dist/index.js
+// ...
+var import_react = __toESM(require_react());
+function src_default() {
+  console.info(import_react.default);
+}
+```
+
+</CH.Spotlight>
+
+不过在实际的开发场景中，可能会遇到某个第三方依赖无法处理的情况，此时可以使用以下 API 对它们进行 **external** 处理。
+
+- [`buildConfig.externals`](/api/config/build-config#externals)
+
 ### 排除指定第三方依赖
 
-而除了 `buildConfig.autoExternal` API 以外，`buildConfig.externals` 也可以控制哪些第三方依赖要进行处理。我们可以组合这两个
+在上面我们提到了 `buildConfig.autoExternal` API 的用途，同时 `buildConfig.externals` 也可以控制哪些第三方依赖要进行处理。因此我们可以组合这两个
 API 对项目的依赖进行更细微的处理。
 
 例如当我们需要仅对某些依赖不进行打包处理的时候，可以按照如下方式进行配置：

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

@@ -66,6 +66,10 @@ pnpm test
 npx @modern-js/create your-project-dir-name
 ```
 
+:::info
+执行 `npx @modern-js/create -h` 查看更多命令行参数
+:::
+
 接着在问题交互中，按照如下选择：
 
 ```bash
@@ -86,5 +90,5 @@ npx @modern-js/create your-project-dir-name
 选择适合你的教程：
 
 - 我是初学者，需要学习 Module Tools 的[基础使用](/guide/basic/before-getting-started)。
-- 我已经初步掌握了 Module Tools 的使用，可以学习 Module Tools 的[高级使用](/guide/basic/before-getting-started)。
-- 我是项目的维护者，需要学习如何开发 Module Tools 的插件以及了解更多关于 Module Tools 进阶的内容。
+- 我已经初步掌握了 Module Tools 的使用，可以学习 Module Tools 的[进阶指南](/guide/advance/in-depth-about-build)。
+- 我需要扩展项目能力，需要学习如何开发 Module Tools 的[插件](/plugins/guide/getting-started)。

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@modern-js/module-tools-docs",
-  "version": "2.4.0",
-  "description": "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",
+  "license": "MIT",
+  "version": "2.5.0",
   "main": "index.js",
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
   "dependencies": {
     "@code-hike/mdx": "^0.7.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "shiki": "^0.11.1",
-    "@modern-js/doc-plugin-auto-sidebar": "2.4.0",
-    "@modern-js/doc-tools": "2.4.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.5.0",
+    "@modern-js/doc-tools": "2.5.0"
   },
   "scripts": {
     "dev": "modern dev",
-    "build:doc": "modern build"
+    "build:doc": "modern build",
+    "preview": "modern preview"
   }
 }