@path-ioc/unplugin 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +28 -25
  2. package/README.zh-CN.md +118 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <div align="center">
2
2
  <h1>@path-ioc/unplugin</h1>
3
3
  <p><b>Universal Dev Plugin for Path-IoC (Virtual Container & Type Generator)</b></p>
4
- <p>跨构建工具（Vite / Rolldown / Webpack / Rspack / Rollup / Esbuild）的通用虚拟模块注入与 TypeScript 类型自动推导插件</p>
4
+ <p>Cross-bundler virtual module injector & automated TypeScript type generator for Vite, Rolldown, Webpack 5, Rspack, Rollup, and Esbuild</p>
5
5
 
6
6
  <p>
7
7
  <a href="https://www.npmjs.com/package/@path-ioc/unplugin"><img src="https://img.shields.io/npm/v/@path-ioc/unplugin.svg" alt="NPM version"></a>
@@ -12,28 +12,32 @@
12
12
  <a href="https://rspack.dev"><img src="https://img.shields.io/badge/Rspack-compatible-EE6338?logo=rspack&logoColor=white" alt="Rspack"></a>
13
13
  <a href="https://webpack.js.org"><img src="https://img.shields.io/badge/Webpack-5-8DD6F9?logo=webpack&logoColor=black" alt="Webpack"></a>
14
14
  </p>
15
+
16
+ <p>
17
+ <b>English</b> | <a href="./README.zh-CN.md">简体中文</a> | <a href="https://path-ioc.dev/api/unplugin">Official Docs</a>
18
+ </p>
15
19
  </div>
16
20
 
17
- > 💡 **核心定位**：`@path-ioc/unplugin` 是 [`@path-ioc/core`](../core) 的编译期伴生驱动引擎。在真实生产工程中，两者密不可分：`unplugin` 负责在构建期自动扫描物理目录并实时生成 `.d.ts` 类型推导，`core` 负责在运行时进行极速无锁 DAG 拓扑装配。
18
- > **完整的架构设计哲学、模块编写规范、依赖查找与端到端完整指南，请直接查阅：**
19
- > 📖 **[`@path-ioc/core` 官方指南](../core/README.md)** 或访问官方主站 **[https://path-ioc.dev](https://path-ioc.dev)**。
21
+ > 💡 **Architectural Positioning**: `@path-ioc/unplugin` is the companion build-time engine for [`@path-ioc/core`](../core). In production projects, both work as one: `unplugin` scans physical module directories at build time and synthesizes real-time `.d.ts` definitions, while `core` executes lock-free DAG topological scheduling at runtime.
22
+ > **For the full architecture manifesto, design principles, and end-to-end guide:**
23
+ > 📖 **[Read the @path-ioc/core Guide](../core/README.md)** or visit **[https://path-ioc.dev](https://path-ioc.dev)**.
20
24
 
21
25
  ---
22
26
 
23
- ## 核心职能 (Key Responsibilities)
27
+ ## Key Responsibilities
24
28
 
25
- - **全构建器原生支持 (Universal Bundler Support)**：
26
- 基于 `unplugin` 规范，一套逻辑原生适配 **Vite**、**Rolldown (Rust)**、**Webpack 5**、**Rspack**、**Rollup** 与 **Esbuild**。
27
- - **`virtual:modular-container` 虚拟模块流式注入**：
28
- 构建期自动扫描 `src/modules/**/index.{ts,tsx}`，动态生成全量模块注册表。在 Vite/Rolldown/Rollup 环境下纯内存流式注入，在 Webpack/Rspack 下自动创建临时代理桥接。
29
- - **TypeScript 零配置类型合成**：
30
- 开发时与 HMR 热更新时毫秒级生成 `ignore.modular.d.ts`，自动扩充全局 `ModularContainer` 接口，解构享 100% 准确 IDE 提示。
31
- - **Git 规避自愈 (`.gitignore` 自动维护)**：
32
- 自动向项目 `.gitignore` 补充 `ignore.*` 规则，防止生成的临时声明污染版本控制。
29
+ - **Universal Bundler Support**:
30
+ Built on the `unplugin` standard to natively support **Vite**, **Rolldown (Rust)**, **Webpack 5**, **Rspack**, **Rollup**, and **Esbuild** with a unified configuration API.
31
+ - **`virtual:modular-container` Streaming Module Injection**:
32
+ Automatically scans `src/modules/**/index.{ts,tsx}` during development/build to generate the complete module registry. Injected purely in-memory for Vite/Rolldown/Rollup, and dynamically bridged for Webpack/Rspack.
33
+ - **Zero-Config TypeScript Type Synthesis**:
34
+ Generates `ignore.modular.d.ts` in milliseconds during dev mode and HMR, augmenting the global `ModularContainer` interface with 100% accurate IDE auto-completion.
35
+ - **Automatic `.gitignore` Self-Healing**:
36
+ Appends `ignore.*` rules to your project's `.gitignore` automatically to prevent ephemeral declaration files from polluting version control.
33
37
 
34
38
  ---
35
39
 
36
- ## 安装 (Installation)
40
+ ## Installation
37
41
 
38
42
  ```bash
39
43
  pnpm add -D @path-ioc/unplugin
@@ -42,7 +46,7 @@ pnpm add @path-ioc/core
42
46
 
43
47
  ---
44
48
 
45
- ## 构建工具集成速查 (Bundler Quick Reference)
49
+ ## Bundler Quick Reference
46
50
 
47
51
  ### 1. Vite (`vite.config.ts`)
48
52
  ```typescript
@@ -92,24 +96,23 @@ import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
92
96
 
93
97
  ---
94
98
 
95
- ## 插件配置项 (Plugin Options)
99
+ ## Plugin Options
96
100
 
97
- | 配置项 | 类型 | 默认值 | 描述 |
101
+ | Option | Type | Default | Description |
98
102
  | :--- | :--- | :--- | :--- |
99
- | **`modulesPath`** | `string` | `'src/modules'` | 模块扫描的物理根目录路径。 |
100
- | **`typeFileOutput`** | `string` | `'types'` | 自动生成的类型声明文件 `ignore.modular.d.ts` 存放相对目录。 |
103
+ | **`modulesPath`** | `string` | `'src/modules'` | Root directory scanned for modular IoC entrypoints (`index.ts/tsx`). |
104
+ | **`typeFileOutput`** | `string` | `'types'` | Target directory where `ignore.modular.d.ts` is generated. |
101
105
 
102
106
  ---
103
107
 
104
- ## 真实应用与模块编写
105
-
106
- 关于如何编写 `main` 纯函数模块、声明依赖、在应用入口一行唤醒容器，请参阅：
107
- 👉 **[查看 @path-ioc/core 完整实战指南](../core/README.md)**
108
+ ## Production Usage & Module Writing
108
109
 
110
+ For practical guidance on creating modules with `main`, declaring dependencies, and igniting the container, please see:
111
+ 👉 **[Read @path-ioc/core Documentation](../core/README.md)**
109
112
 
110
113
  ---
111
114
 
112
- ## 许可证 (License)
115
+ ## License
113
116
 
114
117
  Released under the [MIT License](./LICENSE).
115
- Copyright © 2026 [Path-IoC Organization](https://github.com/path-ioc) & Lian HanLin.
118
+ Copyright © 2026-present [Path-IoC Organization](https://github.com/path-ioc) & Lian HanLin.
package/README.zh-CN.md ADDED
@@ -0,0 +1,118 @@
1
+ <div align="center">
2
+ <h1>@path-ioc/unplugin</h1>
3
+ <p><b>Universal Dev Plugin for Path-IoC (Virtual Container & Type Generator)</b></p>
4
+ <p>跨构建工具（Vite / Rolldown / Webpack / Rspack / Rollup / Esbuild）的通用虚拟模块注入与 TypeScript 类型自动推导插件</p>
5
+
6
+ <p>
7
+ <a href="https://www.npmjs.com/package/@path-ioc/unplugin"><img src="https://img.shields.io/npm/v/@path-ioc/unplugin.svg" alt="NPM version"></a>
8
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/@path-ioc/unplugin.svg" alt="License"></a>
9
+ <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
10
+ <a href="https://vite.dev"><img src="https://img.shields.io/badge/powered%20by-Vite-646CFF?logo=vite&logoColor=white" alt="Vite"></a>
11
+ <a href="https://rolldown.rs"><img src="https://img.shields.io/badge/Rolldown-ready-FF6B6B?logo=rust&logoColor=white" alt="Rolldown"></a>
12
+ <a href="https://rspack.dev"><img src="https://img.shields.io/badge/Rspack-compatible-EE6338?logo=rspack&logoColor=white" alt="Rspack"></a>
13
+ <a href="https://webpack.js.org"><img src="https://img.shields.io/badge/Webpack-5-8DD6F9?logo=webpack&logoColor=black" alt="Webpack"></a>
14
+ </p>
15
+
16
+ <p>
17
+ <a href="./README.md">English</a> | <b>简体中文</b> | <a href="https://path-ioc.dev/zh/api/unplugin">官方文档</a>
18
+ </p>
19
+ </div>
20
+
21
+ > 💡 **核心定位**：`@path-ioc/unplugin` 是 [`@path-ioc/core`](../core) 的编译期伴生驱动引擎。在真实生产工程中，两者密不可分：`unplugin` 负责在构建期自动扫描物理目录并实时生成 `.d.ts` 类型推导，`core` 负责在运行时进行极速无锁 DAG 拓扑装配。
22
+ > **完整的架构设计哲学、模块编写规范、依赖查找与端到端完整指南，请直接查阅：**
23
+ > 📖 **[`@path-ioc/core` 官方指南](../core/README.zh-CN.md)** 或访问官方主站 **[https://path-ioc.dev/zh/](https://path-ioc.dev/zh/)**。
24
+
25
+ ---
26
+
27
+ ## 核心职能 (Key Responsibilities)
28
+
29
+ - **全构建器原生支持 (Universal Bundler Support)**：
30
+ 基于 `unplugin` 规范，一套逻辑原生适配 **Vite**、**Rolldown (Rust)**、**Webpack 5**、**Rspack**、**Rollup** 与 **Esbuild**。
31
+ - **`virtual:modular-container` 虚拟模块流式注入**：
32
+ 构建期自动扫描 `src/modules/**/index.{ts,tsx}`，动态生成全量模块注册表。在 Vite/Rolldown/Rollup 环境下纯内存流式注入，在 Webpack/Rspack 下自动创建临时代理桥接。
33
+ - **TypeScript 零配置类型合成**：
34
+ 开发时与 HMR 热更新时毫秒级生成 `ignore.modular.d.ts`，自动扩充全局 `ModularContainer` 接口，解构享 100% 准确 IDE 提示。
35
+ - **Git 规避自愈 (`.gitignore` 自动维护)**：
36
+ 自动向项目 `.gitignore` 补充 `ignore.*` 规则，防止生成的临时声明污染版本控制。
37
+
38
+ ---
39
+
40
+ ## 安装 (Installation)
41
+
42
+ ```bash
43
+ pnpm add -D @path-ioc/unplugin
44
+ pnpm add @path-ioc/core
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 构建工具集成速查 (Bundler Quick Reference)
50
+
51
+ ### 1. Vite (`vite.config.ts`)
52
+ ```typescript
53
+ import { defineConfig } from "vite";
54
+ import { vitePlugin as pathIoc } from "@path-ioc/unplugin";
55
+
56
+ export default defineConfig({
57
+ plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
58
+ });
59
+ ```
60
+
61
+ ### 2. Rolldown (`rolldown.config.ts`)
62
+ ```typescript
63
+ import { defineConfig } from "rolldown";
64
+ import { rolldownPlugin as pathIoc } from "@path-ioc/unplugin";
65
+
66
+ export default defineConfig({
67
+ plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
68
+ });
69
+ ```
70
+
71
+ ### 3. Rspack (`rspack.config.js`)
72
+ ```javascript
73
+ const { rspackPlugin: pathIoc } = require("@path-ioc/unplugin");
74
+
75
+ module.exports = {
76
+ plugins: [pathIoc()],
77
+ };
78
+ ```
79
+
80
+ ### 4. Webpack 5 (`webpack.config.js`)
81
+ ```javascript
82
+ const { webpackPlugin: pathIoc } = require("@path-ioc/unplugin");
83
+
84
+ module.exports = {
85
+ plugins: [pathIoc({ modulesPath: "src/modules" })],
86
+ };
87
+ ```
88
+
89
+ ### 5. Rollup (`rollup.config.js`) / Esbuild
90
+ ```javascript
91
+ // Rollup
92
+ import { rollupPlugin as pathIoc } from "@path-ioc/unplugin";
93
+ // Esbuild
94
+ import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
95
+ ```
96
+
97
+ ---
98
+
99
+ ## 插件配置项 (Plugin Options)
100
+
101
+ | 配置项 | 类型 | 默认值 | 描述 |
102
+ | :--- | :--- | :--- | :--- |
103
+ | **`modulesPath`** | `string` | `'src/modules'` | 模块扫描的物理根目录路径。 |
104
+ | **`typeFileOutput`** | `string` | `'types'` | 自动生成的类型声明文件 `ignore.modular.d.ts` 存放相对目录。 |
105
+
106
+ ---
107
+
108
+ ## 真实应用与模块编写
109
+
110
+ 关于如何编写 `main` 纯函数模块、声明依赖、在应用入口一行唤醒容器，请参阅：
111
+ 👉 **[查看 @path-ioc/core 完整实战指南](../core/README.zh-CN.md)**
112
+
113
+ ---
114
+
115
+ ## 许可证 (License)
116
+
117
+ Released under the [MIT License](./LICENSE).
118
+ Copyright © 2026 [Path-IoC Organization](https://github.com/path-ioc) & Lian HanLin.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@path-ioc/unplugin",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Universal dev plugin for Path-IoC generating virtual modular container and TypeScript typings",
5
5
  "keywords": [
6
6
  "unplugin",