@modern-js/module-tools-docs 2.22.1 → 2.23.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @modern-js/module-tools-docs
 
+## 2.23.0
+
+### Patch Changes
+
+- Updated dependencies [7e6fb5f]
+  - @modern-js/doc-plugin-auto-sidebar@2.23.0
+  - @modern-js/doc-tools@2.23.0
+
 ## 2.22.1
 
 ### Patch Changes

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

@@ -8,8 +8,8 @@ This section describes all the configuration of Module Tools for building
 
 ## alias
 
-- Type: `Record<string, string> | Function`
-- Default: `{'@': 'src',}`
+- **Type**: `Record<string, string> | Function`
+- **Default**: `{'@': 'src',}`
 
 :::tip
 For TypeScript projects, you only need to configure [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths) in `tsconfig.json`, Module Tools will automatically recognize the alias in `tsconfig.json`, so there is no need to configure the `alias` field additionally.
@@ -59,22 +59,22 @@ export default {
 
 Static resource output path, will be based on [outDir](/api/config/build-config#outDir)
 
-- Type: `string`
-- Default: `assets`
+- **Type**: `string`
+- **Default**: `assets`
 
 ### limit
 
 Threshold for automatically inlining static resources when building, resources less than 10 KB will be automatically inlined into the bundle product
 
-- Type: `number`
-- Default: `10 * 1024`
+- **Type**: `number`
+- **Default**: `10 * 1024`
 
 ### publicPath
 
 The CDN prefix given to unlinked resources when packaging
 
-- Type: `string`
-- Default: `undefined`
+- **Type**: `string`
+- **Default**: `undefined`
 
 ```js modern.config.ts
 export default {
@@ -92,8 +92,8 @@ At this point, all static resources will be prefixed with `https://xxx/`
 
 Packaged to handle svg as a React component, options reference [svgr](https://react-svgr.com/docs/options/), plus support for two configuration items `include` and `exclude` to match the svg file to be handled
 
-- Type: `boolean | Object`
-- Default: `false`
+- **Type**: `boolean | Object`
+- **Default**: `false`
 
 When svgr feature is enabled, you can use svg as a component using the default export.
 
@@ -128,22 +128,22 @@ declare module '*.svg' {
 
 Set the matching svg file
 
-- Type: `string | RegExp | (string | RegExp)[]`
-- Default: `/\.svg$/`
+- **Type**: `string | RegExp | (string | RegExp)[]`
+- **Default**: `/\.svg$/`
 
 #### exclude
 
 Set unmatched svg files
 
-- Type: `string | RegExp | (string | RegExp)[]`
-- Default: `undefined`
+- **Type**: `string | RegExp | (string | RegExp)[]`
+- **Default**: `undefined`
 
 ## autoExternal
 
 Automatically externalize project dependencies and peerDependencies and not package them into the final bundle
 
-- Type: `boolean | Object`
-- Default: `true`
+- **Type**: `boolean | Object`
+- **Default**: `true`
 
 When we want to turn off the default handling behavior for third-party dependencies, we can do so by:
 
@@ -173,29 +173,29 @@ export default defineConfig({
 
 Whether or not the dep dependencies of the external project are needed
 
-- Type: `boolean`
-- Default: `true`
+- **Type**: `boolean`
+- **Default**: `true`
 
 ### peerDependencies
 
 Whether to require peerDep dependencies for external projects
 
-- Type: `boolean`
-- Default: `true`
+- **Type**: `boolean`
+- **Default**: `true`
 
 ## buildType
 
 The build type, `bundle` will package your code, `bundleless` will only do the code conversion
 
-- Type: `'bundle' | 'bundleless'`
-- Default: `bundle`
+- **Type**: `'bundle' | 'bundleless'`
+- **Default**: `bundle`
 
 ## copy
 
 Copies the specified file or directory into the build output directory
 
-- Type: `Array`
-- Default: `[]`
+- **Type**: `Array`
+- **Default**: `[]`
 
 ```js
 export default {
@@ -211,8 +211,8 @@ Reference for array settings: [copy-webpack-plugin patterns](https://github.com/
 
 Define global variables that will be injected into the code
 
-- Type: `Record<string, string>`
-- Default: `{}`
+- **Type**: `Record<string, string>`
+- **Default**: `{}`
 
 Since the `define` function is implemented by global text replacement, you need to ensure that the global variable values are strings. A safer approach is to convert the value of each global variable to a string, using `JSON.stringify`, as follows.
 
@@ -247,8 +247,8 @@ The use of SWC Transform can reduce the impact of auxiliary functions on the vol
 
 The dts file generates the relevant configuration, by default it generates.
 
-- Type: `false | Object`
-- Default:
+- **Type**: `false | Object`
+- **Default**:
 
 ```js
 {
@@ -267,36 +267,46 @@ Whether to allow the build to succeed in case of a type error. By default, this
 When this configuration is turned on, there is no guarantee that the type files will be generated properly and accurately. In `buildType: 'bundle'` or Bundle build mode, the type file must not be generated.
 :::
 
-- Type: `boolean`
-- Default: `true`
+- **Type**: `boolean`
+- **Default**: `true`
 
 ### distPath
 
 The output path of the dts file, based on [outDir](/api/config/build-config#outDir)
 
-- Type: `string`
-- Default: `. /types`
+- **Type**: `string`
+- **Default**: `. /types`
 
 ### only
 
 Generate only dts files, not js files
 
-- Type: `boolean`
-- Default: `false`
+- **Type**: `boolean`
+- **Default**: `false`
+
+### respectExternal
+
+When set to `false`, the type of third-party packages will be excluded from the bundle, when set to `true`, it will determine whether third-party types need to be bundled based on [externals](#externals).
+
+When bundle d.ts, export is not analyzed, so any third-party package type you use may break your build, which is obviously uncontrollable.
+So we can avoid it with this configuration.
+
+- **Type**: `boolean`
+- Default value: `true`
 
 ### tsconfigPath
 
 Path to the tsconfig file
 
-- Type: `string`
-- Default: `. /tsconfig.json`
+- **Type**: `string`
+- **Default**: `. /tsconfig.json`
 
 ## esbuildOptions
 
 Directly modify [esbuild configuration](https://esbuild.github.io/api/)
 
-- Type: `Function`
-- Default: `c => c`
+- **Type**: `Function`
+- **Default**: `c => c`
 
 For example, if we need to modify the file extension of the generated files:
 
@@ -328,8 +338,8 @@ By default, the output JS code may depend on helper functions to support the tar
 
 When using SWC Transform for code transformation, you can enable the `externalHelpers` configuration to convert inline helper functions to import them from the external module `@swc/helpers`.
 
-* **Type**: `boolean`
-* **Default**: `false`
+- **Type**: `boolean`
+- **Default**: `false`
 
 Below is a comparison of the product changes before and after using this configuration.
 
@@ -370,22 +380,22 @@ export var yourCode = function() {
 
 Configure external dependencies that will not be packaged into the final bundle
 
-- Type: `(string | RegExp)[]`
-- Default: `[]`
+- **Type**: `(string | RegExp)[]`
+- **Default**: `[]`
 
 ## format
 
 The format of the js product output, where `iife` and `umd` can only take effect when `buildType` is `bundle`
 
-- Type: `'esm' | 'cjs' | 'iife' | 'umd'`
-- Default: `cjs`
+- **Type**: `'esm' | 'cjs' | 'iife' | 'umd'`
+- **Default**: `cjs`
 
 ## input
 
 Specify the entry file for the build, in the form of an array that can specify the directory
 
-- Type: `string[] | Record<string, string>`
-- Default: `['src/index.ts']` in `bundle` mode, `['src']` in `bundleless` mode
+- **Type**: `string[] | Record<string, string>`
+- **Default**: `['src/index.ts']` in `bundle` mode, `['src']` in `bundleless` mode
 
 ```js modern.config.ts
 export default {
@@ -399,22 +409,22 @@ export default {
 
 Specify the compilation method of jsx, default support React17, automatically inject jsx runtime code
 
-- Type: `automatic | classic`
-- Default: `automatic`
+- **Type**: `automatic | classic`
+- **Default**: `automatic`
 
 ## metafile
 
 esbuild to produce some metadata about the build in JSON format, which can be visualized by tools such as [bundle-buddy](https://bundle-buddy.com/esbuild)
 
-- Type: `boolean`
-- Default: `false`
+- **Type**: `boolean`
+- **Default**: `false`
 
 ## minify
 
 Use esbuild or terser to compress code, also pass [terserOptions](https://github.com/terser/terser#minify-options)
 
-- Type: `'terser' | 'esbuild' | false | Object`
-- Default: `false`
+- **Type**: `'terser' | 'esbuild' | false | Object`
+- **Default**: `false`
 
 ```js modern.config.ts
 export default {
@@ -432,15 +442,15 @@ export default {
 
 Specifies the output directory of the build
 
-- Type: `string`
-- Default: `dist`
+- **Type**: `string`
+- **Default**: `dist`
 
 ## platform
 
 Generates code for the node environment by default, you can also specify `browser` which will generate code for the browser environment
 
-- Type: `'browser' | 'node'`
-- Default: `node`
+- **Type**: `'browser' | 'node'`
+- **Default**: `node`
 
 ## redirect
 
@@ -467,16 +477,16 @@ export default {
 
 Module sideEffects
 
-- Type: `RegExg[] | (filePath: string, isExternal: boolean) => boolean | boolean`
-- Default: `undefined`
+- **Type**: `RegExg[] | (filePath: string, isExternal: boolean) => boolean | boolean`
+- **Default**: `undefined`
 
-Normally, we configure the module's side effects via the sideEffects field in package.json, but in some cases, The package.json of a three-party package is unreliable.Such as when we reference a three-party package style file
+Normally, we configure the module's side effects via the sideEffects field in package.json, but in some cases, The package.json of a third-party package is unreliable.Such as when we reference a third-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
+But the package.json of this third-party package does not have the style file configured in the sideEffects
 
 ```json other-package/package.json
 {
@@ -511,15 +521,15 @@ After adding this configuration, the sideEffects field in package.json will no l
 
 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`.
 
-- Type: `string`
-- Default: `src`
+- **Type**: `string`
+- **Default**: `src`
 
 ## sourceMap
 
 Whether to generate sourceMap or not
 
-- Type: `boolean | 'inline' | 'external'`
-- Default: `false`
+- **Type**: `boolean | 'inline' | 'external'`
+- **Default**: `false`
 
 ## sourceType
 
@@ -532,8 +542,8 @@ Sets the format of the source code. By default, the source code will be treated
 
 Whether to enable code splitting
 
-- Type: `boolean`
-- Default: `false`
+- **Type**: `boolean`
+- **Default**: `false`
 
 ## style
 
@@ -547,15 +557,15 @@ less-related configuration
 
 Refer to [less](https://less.bootcss.com/usage/#less-options) for detailed configuration
 
-- Type: `Object`
-- Default: `{ javascriptEnabled: true }`
+- **Type**: `Object`
+- **Default**: `{ javascriptEnabled: true }`
 
 #### additionalData
 
 Add `Less` code to the beginning of the entry file.
 
-- Type: `string`
-- Default: `undefined`
+- **Type**: `string`
+- **Default**: `undefined`
 
 ```js modern.config.ts
 export default {
@@ -573,8 +583,8 @@ export default {
 
 Configure the implementation library used by `Less`, if not specified, the built-in version used is `4.1.3`
 
-- Type: `string | Object`
-- Default: `undefined`
+- **Type**: `string | Object`
+- **Default**: `undefined`
 
 Specify the implementation library for `Less` when the `Object` type is specified
 
@@ -612,15 +622,15 @@ sass-related configuration
 
 Refer to [node-sass](https://github.com/sass/node-sass#options) for detailed configuration
 
-- Type: `Object`
-- Default: `{}`
+- **Type**: `Object`
+- **Default**: `{}`
 
 #### additionalData
 
 Add `Sass` code to the beginning of the entry file.
 
-- Type: `string | Function`
-- Default: `undefined`
+- **Type**: `string | Function`
+- **Default**: `undefined`
 
 ```js modern.config.ts
 export default {
@@ -639,8 +649,8 @@ export default {
 
 Configure the implementation library used by `Sass`, the built-in version used is `1.5.4` if not specified
 
-- Type: `string | Object`
-- Default: `undefined`
+- **Type**: `string | Object`
+- **Default**: `undefined`
 
 Specify the implementation library for `Sass` when the `Object` type is specified
 
@@ -675,14 +685,14 @@ export default {
 - plugins
 - processOptions
 
-See [postcss](https://github.com/postcss/postcss#options) for detailed configuration
+See [PostCSS](https://github.com/postcss/postcss#options) for detailed configuration
 
 ### inject
 
 Configure whether to insert style into js in packaged mode
 
-- Type: `boolean`
-- Default: `false`
+- **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.
 
@@ -703,7 +713,7 @@ style_inject_es_default(css_248z);
 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
+- 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 third-party 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"
@@ -717,8 +727,8 @@ This can be fixed by configuring [sideEffects](#sideeffects) in this case.
 
 Enable CSS Modules automatically based on the filename.
 
-- Type: `boolean | RegExp`
-- Default: `true`
+- **Type**: `boolean | RegExp`
+- **Default**: `true`
 
 `true` : Enables CSS Modules for style files ending with `.module.css` `.module.less` `.module.scss` `.module.sass` filenames
 
@@ -730,8 +740,8 @@ Enable CSS Modules automatically based on the filename.
 
 CSS Modules configuration
 
-- Type: `Object`
-- Default: `{}`
+- **Type**: `Object`
+- **Default**: `{}`
 
 A common configuration is `localsConvention`, which changes the class name generation rules for css modules
 
@@ -763,8 +773,8 @@ For detailed configuration see [postcss-modules](https://github.com/madyankin/po
 
 tailwindcss related configuration
 
-- Type: `Object | Function`
-- Default: `see configuration details below`
+- **Type**: `Object | Function`
+- **Default**: `see configuration details below`
 
 <details>
   <summary>Tailwind CSS configuration details</summary>
@@ -796,8 +806,8 @@ The rest of the usage is the same as Tailwind CSS: [Quick Portal](https://tailwi
 
 Specify the target environment for the build
 
-- Type: `'es5' | 'es6' | 'es2015' | 'es2016' | 'es2017' | 'es2018' | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'esnext'`
-- Default: `'es6'`
+- **Type**: `'es5' | 'es6' | 'es2015' | 'es2016' | 'es2017' | 'es2018' | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'esnext'`
+- **Default**: `'es6'`
 
 <!-- ## transformImport
 
@@ -837,8 +847,8 @@ Reference the [Import Plugin - Notes](plugins/official-list/plugin-import.html#N
 
 Specify global variables for external import of umd products
 
-- Type: `Record<string, string>`
-- Default: `{}`
+- **Type**: `Record<string, string>`
+- **Default**: `{}`
 
 ```js modern.config.ts
 export default {
@@ -857,8 +867,8 @@ At this point, `react` and `react-dom` will be seen as global variables imported
 
 Specifies the module name of the umd product
 
-- Type: `string` | `Function`
-- Default: `name => name`
+- **Type**: `string` | `Function`
+- **Default**: `name => name`
 
 ```js
 export default {

package/docs/en/guide/best-practices/components.mdx

@@ -204,7 +204,7 @@ The following capabilities are currently supported for developing styles.
 
 ### CSS/PostCSS
 
-The module project supports PostCSS and has the following built-in postcss plugins.
+The module project supports PostCSS and has the following built-in PostCSS plugins.
 
 - [flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes)
 - [custom-properties](https://github.com/postcss/postcss-custom-properties)

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

@@ -6,4 +6,4 @@
 * [@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.
 * [@modern-js/plugin-module-node-polyfill](./plugin-node-polyfill.mdx)： Inject Polyfills of Node core modules in the browser side.
 * [@modern-js/plugin-module-polyfill](./plugin-polyfill.md)：Inject polyfill for unsupported features used in your code.
-* [@modern-js/plugin-module-babel](./plugin-babel.md)：Use babel to transform your code.
+* [@modern-js/plugin-module-babel](./plugin-babel.md)：Use Babel to transform your code.

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

@@ -50,7 +50,7 @@ type options = {
 
 ### targets
 
-See [babel target](https://babeljs.io/docs/options#targets).
+See [Babel target](https://babeljs.io/docs/options#targets).
 
 This is a example.
 

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

@@ -325,6 +325,15 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `false`
 
+### respectExternal
+
+当设为 `false` 时，不会打包任何三方包类型，设为 `true` 时，会根据[externals](#externals)来决定是否需要打包三方类型。
+
+在对类型文件进行打包时，构建工具还未对 export 进行分析，因此当你引用的任何一个三方包出现类型错误时，都可能会中断当前的构建流程，这会导致构建流程不可控，因此我们可以通过这个配置来避免该问题。
+
+- 类型： `boolean`
+- 默认值： `true`
+
 ### tsconfigPath
 
 TypeScript 配置文件的路径。
@@ -369,9 +378,8 @@ export default defineConfig({
 
 当在使用 SWC Transform 进行代码转换的时候，可以启动 `externalHelpers` 配置，将内联的辅助函数转换为从外部模块 `@swc/helpers` 导入这些辅助函数。
 
-* 类型：`boolean`
-* 默认值：`false`
-
+- 类型：`boolean`
+- 默认值：`false`
 
 下面是使用该配置前后的产物变化比较。
 
@@ -408,7 +416,6 @@ export var yourCode = function() {
 }
 ```
 
-
 ## externals
 
 配置外部依赖，不会被打包到最终的 bundle 中。
@@ -735,7 +742,7 @@ export default defineConfig({
 - plugins
 - processOptions
 
-详细配置查看 [postcss](https://github.com/postcss/postcss#options)。
+详细配置查看 [PostCSS](https://github.com/postcss/postcss#options)。
 
 ### inject
 
@@ -865,8 +872,8 @@ const tailwind = {
 
 提供与 babel-plugin-import 等价的能力和配置，基于 SWC 实现。
 
-* 类型：`Array`
-* 默认值：`[]`
+- 类型：`Array`
+- 默认值：`[]`
 
 数组元素为一个 babel-plugin-import 的配置对象。配置对象可以参考 [options](https://github.com/umijs/babel-plugin-import#options)。
 
@@ -895,7 +902,6 @@ export default defineConfig({
 
 参考[【Import 插件——注意事项】](plugins/official-list/plugin-import.html#注意事项)
 
-
 ## umdGlobals
 
 指定 UMD 产物外部导入的全局变量。

package/docs/zh/guide/best-practices/components.mdx

@@ -208,7 +208,7 @@ export default {
 
 ### CSS/PostCSS
 
-模块工程支持 PostCSS，并且内置了以下 postcss 插件：
+模块工程支持 PostCSS，并且内置了以下 PostCSS 插件：
 
 - [flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes)
 - [custom-properties](https://github.com/postcss/postcss-custom-properties)

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

@@ -6,4 +6,4 @@
 * [@modern-js/plugin-module-banner](./plugin-banner.md)：为每个 JS 和 CSS 文件的顶部和底部添加自定义内容，例如版权信息。
 * [@modern-js/plugin-module-node-polyfill](./plugin-node-polyfill.mdx)：会自动注入 Node 核心模块在浏览器端的 polyfills。
 * [@modern-js/plugin-module-polyfill](./plugin-polyfill.md)：为你的代码中使用到的不支持的功能注入 polyfill。
-* [@modern-js/plugin-module-babel](./plugin-babel.md)：使用 babel 转换你的代码。
+* [@modern-js/plugin-module-babel](./plugin-babel.md)：使用 Babel 转换你的代码。

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

@@ -37,7 +37,7 @@ export default defineConfig({
 
 ## 配置
 
-See [babel options](https://babeljs.io/docs/options)
+See [Babel options](https://babeljs.io/docs/options)
 
 下面是一个配置了`@babel/preset-env`的例子：
 

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

@@ -50,9 +50,9 @@ type options = {
 
 ### targets
 
-See [babel target](https://babeljs.io/docs/options#targets).
+参考 [Babel target](https://babeljs.io/docs/options#targets).
 
-This is a example.
+下面是一个例子：
 
 ```ts
 import moduleTools, { defineConfig } from '@modern-js/module-tools';

package/package.json

@@ -9,15 +9,15 @@
     "directory": "packages/document/module-doc"
   },
   "license": "MIT",
-  "version": "2.22.1",
+  "version": "2.23.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.22.1",
-    "@modern-js/doc-tools": "2.22.1"
+    "@modern-js/doc-plugin-auto-sidebar": "2.23.0",
+    "@modern-js/doc-tools": "2.23.0"
   },
   "scripts": {
     "dev": "modern dev",