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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

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/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.11.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.11.0",
-    "@modern-js/doc-tools": "2.11.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.12.0",
+    "@modern-js/doc-tools": "2.12.0"
   },
   "scripts": {
     "dev": "modern dev",