@modern-js/module-tools-docs 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @modern-js/module-tools-docs
 
+## 2.12.0
+
+### Patch Changes
+
+- a90a6a2: feat(plugin-module-node-polyfill, module-docs): add Node Polyfill feature
+  feat(plugin-module-node-polyfill, module-docs): 添加 Node Polyfill 功能。
+- Updated dependencies [d50aaf7]
+  - @modern-js/doc-tools@2.12.0
+  - @modern-js/doc-plugin-auto-sidebar@2.12.0
+
+## 2.11.0
+
+### Minor Changes
+
+- f1b2629: feat: add `dts.abortOnError` config
+  feat: 添加 `dts.abortOnError` 配置
+
+### Patch Changes
+
+- 6118636: fix(module-tools, module-tools-docs): fix svgr usage
+  fix(module-tools, module-tools-docs): 修复 svgr 的使用
+- Updated dependencies [210e9d6]
+- Updated dependencies [95dd73e]
+  - @modern-js/doc-tools@2.11.0
+  - @modern-js/doc-plugin-auto-sidebar@2.11.0
+
 ## 2.10.0
 
 ### Patch Changes

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

@@ -95,6 +95,34 @@ Packaged to handle svg as a React component, options reference [svgr](https://re
 - type: `boolean | Object`
 - default: `false`
 
+When svgr feature is enabled, you can use svg as a component using the default export.
+
+```js index.ts
+// true
+import Logo from './logo.svg';
+
+export default () => <Logo />;
+```
+
+:::warning
+The following usage is not currently supported:
+
+```js index.ts
+import { ReactComponent } from './logo.svg';
+```
+:::
+
+When enabled, the type of svg used can be modified by adding a type definition to the `modern-app-env.d.ts` file:
+
+``` ts modern-app-env.d.ts focus=1:3
+declare module '*.svg' {
+  const src: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
+  export default src;
+}
+
+/// <reference types='@modern-js/module-tools/types' />
+```
+
 #### include
 
 Set the matching svg file
@@ -183,17 +211,30 @@ To prevent excessive global replacement substitution, it is recommended that the
 
 ## dts
 
-The dts file generates the relevant configuration, by default it generates
+The dts file generates the relevant configuration, by default it generates.
 
 - type: `false | Object`
-- default: `{}`
+- default:
 
-### tsconfigPath
+``` js
+{
+  abortOnError: true,
+  distPath: './',
+  only: false,
+  tsconfigPath: './tsconfig.json',
+}
+```
 
-Path to the tsconfig file
+### abortOnError
 
-- type: `string`
-- default: `. /tsconfig.json`
+Whether to allow the build to succeed in case of a type error. By default, this will cause the build to fail in case of a type error.
+
+:::warning
+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`
 
 ### distPath
 
@@ -209,6 +250,13 @@ Generate only dts files, not js files
 - type: `boolean`
 - default: `false`
 
+### tsconfigPath
+
+Path to the tsconfig file
+
+- type: `string`
+- default: `. /tsconfig.json`
+
 ## externals
 
 Configure external dependencies that will not be packaged into the final bundle

package/docs/en/guide/advance/asset.mdx

@@ -17,7 +17,7 @@ By default, module projects are processed for the following static resources:
 For the handling of static files, the module project currently supports the following functions.
 
 - Set the static resource path to `. /assets`.
-- For files over **10kb** they are inlined into the code.
+- Files less than **10kb** will be inlined into the code.
 
 Let us look at the following example:
 

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

@@ -4,5 +4,4 @@
 
 * [@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.
-
-
+* [@modern-js/plugin-module-node-polyfill](./plugin-node-polyfill.mdx)： Inject Polyfills of Node core modules in the browser side.

package/docs/en/plugins/official-list/plugin-node-polyfill.mdx

@@ -0,0 +1,162 @@
+# Node Polyfill Plugin
+
+:::tip About Node Polyfill
+Normally, we don't need to use Node libs on the browser side. However, it is possible to use some Node libs when the code will run on both the Node side and the browser side, and Node Polyfill provides browser versions of polyfills for these Node libs.
+:::
+
+By using the Node Polyfill plugin, Node core libs polyfills are automatically injected into the browser-side, allowing you to use these modules on the browser side with confidence.
+
+## Quick Start
+
+### Install
+
+```bash
+# npm
+npm install @modern-js/plugin-module-node-polyfill -D
+
+# yarn
+yarn add @modern-js/plugin-module-node-polyfill -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-node-polyfill -D
+```
+
+### Register
+
+In Module Tools, you can register plugins in the following way:
+
+```ts
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill(),
+  ],
+});
+```
+
+## Configurations
+
+* **Type**:
+
+```ts
+type NodePolyfillOptions = {
+  exclude?: string[];
+  overrides?: Record<NodePolyfillKey, string>;
+}
+```
+
+### exclude
+
+Exclude the Node Polyfill to be injected.
+
+``` ts focus=7:9
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill({
+      exclude: ['console'],
+    }),
+  ],
+});
+```
+
+### overrides
+
+Override the built-in Node Polyfill.
+
+``` ts focus=7:9
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill({
+      overrides: {
+        fs: path.join(__dirname, './custom-fs.js'),
+      }
+    }),
+  ],
+});
+```
+
+
+## Node Polyfills
+
+### Globals
+
+- `Buffer`
+- `process`
+- `console`
+
+When the above global variables are used directly in code, the corresponding polyfill will be injected.
+
+```ts
+const bufferData = Buffer.from('xxxx');
+```
+
+### Modules
+
+- `assert`
+- `buffer`
+- `console`
+- `constants`
+- `crypto`
+- `domain`
+- `events`
+- `http`
+- `https`
+- `os`
+- `path`
+- `punycode`
+- `process`
+- `querystring`
+- `stream`
+- `_stream_duplex`
+- `_stream_passthrough`
+- `_stream_readable`
+- `_stream_transform`
+- `_stream_writable`
+- `string_decoder`
+- `sys`
+- `timers`
+- `tty`
+- `url`
+- `util`
+- `vm`
+- `zlib`
+
+When the above module is referenced in code via import / require syntax, the corresponding polyfill will be injected.
+
+```ts
+import { Buffer } from 'buffer';
+
+const bufferData = Buffer.from('xxxx');
+```
+
+### Fallbacks
+
+- `child_process`
+- `cluster`
+- `dgram`
+- `dns`
+- `fs`
+- `module`
+- `net`
+- `readline`
+- `repl`
+- `tls`
+
+Currently there is no polyfill for the above modules on the browser side, so when you import the above modules, it will automatically fallback to an empty object.
+
+```ts
+import fs from 'fs';
+
+console.log(fs); // -> {}
+```

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

@@ -98,34 +98,51 @@ export default defineConfig({
 
 ### svgr
 
-打包时将 svg 作为一个 React 组件处理，options 参考 [svgr](https://react-svgr.com/docs/options/)，另外还支持了 `include` 和 `exclude` 两个配置项，用于匹配需要处理的 svg 文件。
+打包时将 SVG 作为一个 React 组件处理，options 参考 [svgr](https://react-svgr.com/docs/options/)，另外还支持了 `include` 和 `exclude` 两个配置项，用于匹配需要处理的 SVG 文件。
 
 - 类型： `boolean | Object`
 - 默认值： `false`
 
-:::tip
-开启 svgr 后，仍然使用 default export 导出 svg，所以你只能导入默认值。
+开启 svgr 功能后，可以使用默认导出的方式将 SVG 当做组件使用。
 
 ```js index.ts
 // true
-import logo from './logo.svg';
+import Logo from './logo.svg';
+
+export default () => <Logo />;
+```
+
+:::warning
 
-// false
+目前不支持下面的用法：
+
+```js index.ts
 import { ReactComponent } from './logo.svg';
 ```
 
 :::
 
+当开启功能后，可以通过在 `modern-app-env.d.ts` 文件中增加类型定义，修改使用 SVG 的类型：
+
+``` ts modern-app-env.d.ts focus=1:3
+declare module '*.svg' {
+  const src: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
+  export default src;
+}
+
+/// <reference types='@modern-js/module-tools/types' />
+```
+
 #### include
 
-设定匹配的 svg 文件
+设定匹配的 SVG 文件
 
 - 类型： `string | RegExp | (string | RegExp)[]`
 - 默认值： `/\.svg$/`
 
 #### exclude
 
-设定不匹配的 svg 文件
+设定不匹配的 SVG 文件
 
 - 类型： `string | RegExp | (string | RegExp)[]`
 - 默认值： `undefined`
@@ -236,17 +253,30 @@ export default defineConfig({
 
 ## dts
 
-类型文件生成的相关配置，默认会生成。
+类型文件生成的相关配置，默认情况会生成。
 
 - 类型： `false | Object`
-- 默认值： `{}`
+- 默认值：
 
-### tsconfigPath
+``` js
+{
+  abortOnError: true,
+  distPath: './',
+  only: false,
+  tsconfigPath: './tsconfig.json',
+}
+```
 
-TypeScript 配置文件的路径。
+### abortOnError
 
-- 类型： `string`
-- 默认值： `./tsconfig.json`
+在出现类型错误的时候，是否允许构建成功。**默认情况下，在出现类型错误的时候会导致构建失败**。
+
+:::warning
+当关闭该配置后，无法保证类型文件能正常生成，且不保证内容正确。在 `buildType: 'bundle'` 或者 Bundle 构建模式下，类型文件一定不会生成。
+:::
+
+- 类型：`boolean`
+- 默认值：`true`
 
 ### distPath
 
@@ -262,6 +292,14 @@ TypeScript 配置文件的路径。
 - 类型： `boolean`
 - 默认值： `false`
 
+### tsconfigPath
+
+TypeScript 配置文件的路径。
+
+- 类型： `string`
+- 默认值： `./tsconfig.json`
+
+
 ## externals
 
 配置外部依赖，不会被打包到最终的 bundle 中。

package/docs/zh/guide/advance/asset.mdx

@@ -17,7 +17,7 @@ sidebar_position: 7
 对于静态文件的处理，模块工程目前默认支持的功能有：
 
 - 设置静态资源路径为 `./assets`。
-- 对于超过 **10kb** 的文件会内联到代码中。
+- 对于不超过 **10kb** 的文件会内联到代码中。
 
 让我们看下面的例子：
 

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

@@ -4,3 +4,4 @@
 
 * [@modern-js/plugin-module-import](./plugin-import.md)：使用 SWC 提供与 `babel-plugin-import` 一样的能力。
 * [@modern-js/plugin-module-banner](./plugin-banner.md)：为每个 JS 和 CSS 文件的顶部和底部添加自定义内容，例如版权信息。
+* [@modern-js/plugin-module-node-polyfill](./plugin-node-polyfill.mdx)：会自动注入 Node 核心模块在浏览器端的 polyfills。

package/docs/zh/plugins/official-list/plugin-node-polyfill.mdx

@@ -0,0 +1,162 @@
+# Node Polyfill 插件
+
+:::tip Node Polyfill 介绍
+通常情况下，我们不会在浏览器端使用 Node 模块。但在当前代码需要同时在 Node 端和浏览器端运行时，用到一些 Node 模块是有可能的。Node Polyfill 为这些 Node 模块提供了浏览器版本的 polyfills。
+:::
+
+通过使用 Node Polyfill 插件，会自动注入 Node 核心模块在浏览器端的 polyfills，让你可以在浏览器端放心使用这些模块。
+
+## 快速开始
+
+### 安装
+
+```bash
+# npm
+npm install @modern-js/plugin-module-node-polyfill -D
+
+# yarn
+yarn add @modern-js/plugin-module-node-polyfill -D
+
+# pnpm
+pnpm add @modern-js/plugin-module-node-polyfill -D
+```
+
+### 注册插件
+
+在 Module Tools 中，你可以按照如下方式注册插件：
+
+```ts
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill(),
+  ],
+});
+```
+
+## 配置
+
+* 类型：
+
+```ts
+type NodePolyfillOptions = {
+  exclude?: string[];
+  overrides?: Record<NodePolyfillKey, string>;
+}
+```
+
+### exclude
+
+排除要注入的 Node Polyfill。
+
+``` ts focus=7:9
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill({
+      exclude: ['console'],
+    }),
+  ],
+});
+```
+
+### overrides
+
+覆盖内置的 Node Polyfill。
+
+``` ts focus=7:9
+import moduleTools, { defineConfig } from '@modern-js/module-tools';
+import { modulePluginNodePolyfill } from '@modern-js/plugin-module-node-polyfill';
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+    modulePluginNodePolyfill({
+      overrides: {
+        fs: path.join(__dirname, './custom-fs.js'),
+      }
+    }),
+  ],
+});
+```
+
+
+## Node Polyfills
+
+### Globals
+
+- `Buffer`
+- `process`
+- `console`
+
+当你在代码中使用以上全局变量时，对应 polyfill 会被自动注入。
+
+```ts
+const bufferData = Buffer.from('xxxx');
+```
+
+### Modules
+
+- `assert`
+- `buffer`
+- `console`
+- `constants`
+- `crypto`
+- `domain`
+- `events`
+- `http`
+- `https`
+- `os`
+- `path`
+- `punycode`
+- `process`
+- `querystring`
+- `stream`
+- `_stream_duplex`
+- `_stream_passthrough`
+- `_stream_readable`
+- `_stream_transform`
+- `_stream_writable`
+- `string_decoder`
+- `sys`
+- `timers`
+- `tty`
+- `url`
+- `util`
+- `vm`
+- `zlib`
+
+当你通过 `require` 或 `import` 等语法在代码中引用以上模块时，对应 polyfill 会被注入。
+
+```ts
+import { Buffer } from 'buffer';
+
+const bufferData = Buffer.from('xxxx');
+```
+
+### Fallbacks
+
+- `child_process`
+- `cluster`
+- `dgram`
+- `dns`
+- `fs`
+- `module`
+- `net`
+- `readline`
+- `repl`
+- `tls`
+
+目前浏览器端没有以上模块的 polyfill，因此当你引用以上模块时，会自动 fallback 为一个空对象。
+
+```ts
+import fs from 'fs';
+
+console.log(fs); // -> {}
+```

package/package.json

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