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

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

@@ -295,7 +295,7 @@ Module sideEffects
 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'
+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
@@ -493,6 +493,35 @@ Configure whether to insert style into js in packaged mode
 - type: `boolean`
 - default: `false`
 
+After opening inject, you will see an extra piece of style code in the js file. For example, if you write `import '. /index.scss'`，you will see the following code.
+
+```js dist/index.js
+// node_modules/.pnpm/style-inject@0.3.0/node_modules/style-inject/dist/style-inject.es.js
+function styleInject(css, ref) {
+  // ...
+}
+var style_inject_es_default = styleInject;
+
+// src/index.scss
+var css_248z = '.body {\n color: black;\n}';
+style_inject_es_default(css_248z);
+```
+
+:::tip {title="Note"}
+
+With `inject` turned on, you need to pay attention to the following points.
+
+- `@import` in the css file will not be processed. So if you have `@import` in your css file, then you need to bring in the css file manually in js (less,scss files don't need it because they will be preprocessed).
+- The impact of `sideEffects` needs to be considered, by default our builder will consider it as a side effect, if the `sideEffects` field set in your project or in the package.json of the three-way package and it does not contain this css file, then you will get a warning
+
+```
+[LIBUILD:ESBUILD_WARN] Ignoring this import because "src/index.scss" was marked as having no side effects by plugin "libuild:adapter"
+```
+
+This can be fixed by configuring [sideEffects](#sideeffects) in this case.
+
+:::
+
 ### autoModules
 
 Enable CSS Modules automatically based on the filename.
@@ -620,7 +649,7 @@ At this point the umd product will go to mount on `global.myLib`
 :::tip
 
 - The module name of the umd product must not conflict with the global variable name.
-- Module names should not contain special characters like `-`, `@`, `/`, etc.
+- Module names will be converted to camelCase, e.g. `my-lib` will be converted to `myLib`, refer to [toIdentifier](https://github.com/babel/babel/blob/main/packages/babel-types/src/converters/toIdentifier.ts).
 
 :::
 

package/docs/en/api/config/{build-preset.md → build-preset.mdx}

@@ -213,6 +213,7 @@ export default defineConfig({
 ## Function
 
 The way the function is configured, you can get the preset value from the `preset` parameter and then modify the build configuration inside to customize your build configuration.
+
 The following is an example of how a function can be configured to compress a build product.
 
 ```js modern.config.ts
@@ -232,3 +233,82 @@ export default defineConfig({
   },
 });
 ```
+
+### Function Parameters
+
+The function form of `buildPreset` contains a function parameter in the form of an object. The object contains the following fields.
+
+* `preset`
+* `extendPreset`
+
+#### `preset`
+
+Type: **Object**
+
+Contains the build configurations corresponding to all available build presets. Build configurations can be used by means of the strings supported by `buildPreset` or by means of underscore commands for those strings. The following are examples of the use of both approaches.
+
+<CH.Spotlight>
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset['npm-library'];
+  },
+});
+```
+---
+
+Use the strings supported by `buildPreset`.
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset['npm-library'];
+  },
+});
+```
+
+---
+
+Use the underscore naming convention for strings supported by `buildPreset`.
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset.NPM_LIBRARY;
+  },
+});
+```
+
+</CH.Spotlight>
+
+#### `extendPreset`
+
+Type: `Function`
+
+Tool function for extending a `buildPreset` to modify the build configuration corresponding to the `buildPreset`.
+
+> The base uses something like `{...oldBuildConfig, ...extendBuildConfig}` approach to processing.
+
+For example, adding the `define` configuration to the `'npm-library'` build preset.
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ extendPreset }) {
+    return extendPreset('npm-library', {
+      define: {
+        VERSION: '1.0.1',
+      },
+    });
+  },
+});
+```
+

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

@@ -352,7 +352,7 @@ export default defineConfig({
 通常情况下，我们通过 package.json 的 `"sideEffects"` 字段来配置模块的副作用，但是在某些情况下，例如我们引用了一个三方包的样式文件。
 
 ```js
-import 'other-package/dist/index.css'
+import 'other-package/dist/index.css';
 ```
 
 但是这个三方包的 package.json 里并没有将样式文件配置到 `"sideEffects"` 里。
@@ -562,6 +562,35 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `false`
 
+开启 inject 后，你会看到打包后的 js 文件中会多出一段 style 的代码。例如你在源码里写了`import './index.scss'`，那么你会看到以下代码。
+
+```js dist/index.js
+// node_modules/.pnpm/style-inject@0.3.0/node_modules/style-inject/dist/style-inject.es.js
+function styleInject(css, ref) {
+  // ...
+}
+var style_inject_es_default = styleInject;
+
+// src/index.scss
+var css_248z = ".body {\n  color: black;\n}";
+style_inject_es_default(css_248z);
+```
+
+:::tip {title="注意"}
+
+开启了 `inject` 后，你需要注意以下几点：
+
+- css 文件中的 `@import` 不会被处理。因此如果你的 css 文件中有 `@import` ，那么你需要在 js 中手动引入 css 文件(less,scss 文件不需要，因为它们会有预处理)。
+- 需要考虑 `sideEffects`的影响，默认情况下我们的构建器会认为它是有副作用的，如果你的项目中或者三方包的 package.json 设置了 `sideEffects` 字段并且没有包含此 css 文件，那么你将会得到一个警告
+
+```
+[LIBUILD:ESBUILD_WARN] Ignoring this import because "src/index.scss" was marked as having no side effects by plugin "libuild:adapter"
+```
+
+此时可以通过配置[sideEffects](#sideeffects)来解决。
+
+:::
+
 ### autoModules
 
 根据文件名自动启用 CSS Modules。
@@ -694,8 +723,8 @@ export default defineConfig({
 
 :::tip
 
-- 需要遵守 UMD 规范，UMD 产物的模块名不能和全局变量名冲突
-- 模块名不能含有 `-`，`@`，`/` 等特殊字符
+- 需要遵守 UMD 规范，UMD 产物的模块名不能和全局变量名冲突。
+- 模块名会被转换为驼峰命名，如 `my-lib` 会被转换为 `myLib`，可参考[toIdentifier](https://github.com/babel/babel/blob/main/packages/babel-types/src/converters/toIdentifier.ts)。
 
 :::
 

package/docs/zh/api/config/{build-preset.md → build-preset.mdx}

@@ -232,3 +232,82 @@ export default defineConfig({
   },
 });
 ```
+
+### 函数参数
+
+`buildPreset` 的函数形式包含了一个对象形式的函数参数。该对象包含以下字段：
+
+* `preset`
+* `extendPreset`
+
+#### `preset`
+
+类型：**Object**
+
+包含了所有可用的构建预设对应的构建配置。可以通过 `buildPreset` 所支持的字符串来使用构建配置，也可以使用这些字符串的下划线命令的方式。下面是两种方式的使用示例：
+
+
+<CH.Spotlight>
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset['npm-library'];
+  },
+});
+```
+---
+
+使用 `buildPreset` 所支持的字符串。
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset['npm-library'];
+  },
+});
+```
+
+---
+
+使用 `buildPreset` 所支持的字符串的下划线命名方式。
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ preset }) {
+    return preset.NPM_LIBRARY;
+  },
+});
+```
+
+</CH.Spotlight>
+
+#### `extendPreset`
+
+类型：`Function`
+
+用于扩展某个 `buildPreset` 的工具函数，可以修改 `buildPreset` 对应的构建配置。
+
+> 底层使用类似 `{...oldBuildConfig, ...extendBuildConfig}` 方式进行处理。
+
+例如在 `'npm-library'` 构建预设的基础上增加 `define` 配置：
+
+```ts modern.config.ts
+import { defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  buildPreset({ extendPreset }) {
+    return extendPreset('npm-library', {
+      define: {
+        VERSION: '1.0.1',
+      },
+    });
+  },
+});
+```

package/package.json

@@ -5,15 +5,15 @@
   "bugs": "https://github.com/modern-js-dev/modern.js/issues",
   "repository": "modern-js-dev/modern.js",
   "license": "MIT",
-  "version": "2.5.0",
+  "version": "2.6.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-plugin-auto-sidebar": "2.5.0",
-    "@modern-js/doc-tools": "2.5.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.6.0",
+    "@modern-js/doc-tools": "2.6.0"
   },
   "scripts": {
     "dev": "modern dev",