@path-ioc/unplugin weekly downloads statistics

@path-ioc/unplugin

Compiler-Runtime Co-design Plugin for Path-IoC (Virtual Container & Type Synthesis)

Cross-bundler virtual module injector & microsecond TypeScript type generator for Vite, Rolldown, Webpack 5, Rspack, Rollup, and Esbuild

English | 简体中文 | Official Docs

💡 Architectural Positioning: Compiler-Runtime Co-design @path-ioc/unplugin is not a mere convenience helper; it is the compiler-side twin intimately coupled with @path-ioc/core, forming the bedrock of Path-IoC's Compiler-Runtime Co-design philosophy. In modern TypeScript development, relying on runtime reflection (reflect-metadata) causes bundling failures, cold-start latency, and lack of true static type awareness. @path-ioc/unplugin shifts module scanning, DAG topological caching, and type synthesis to the build phase, enabling sub-millisecond hot-reloading and 21.2 µs per-request container ignition for the @path-ioc/core runtime. 📖 For module authoring specifications, pure function factories, and end-to-end guides, see: @path-ioc/core Official Guide or visit the official documentation at https://path-ioc.dev/.

Live Demo & Instant Ignition (Live Demo Video)

⚡ Live Architecture Tour: Real-time Coding, Topological Orchestration & Instant Ignition 🌐 Watch Video on path-ioc.dev | ▶ Direct MP4 (1080p HD)

Key Pillars of Compiler-Runtime Co-design

1. Single-Graph Compile Cache Closure (compiledGraph)

Inside the generated virtual:modular-container, @path-ioc/unplugin maintains a module-level closure that holds the pre-compiled compiledGraph:

• One-Time Cold Boot: The entire application's dependency DAG is parsed, validated, and sorted once at process startup (500 nodes compile in just 1.72 ms); • Ultra-Fast Request Ignition: Every invocation of createModularContainer() reuses the cached immutable graph, hydrating an isolated container in just 21.2 microseconds (µs); • Zero Runtime DAG Recomputation: In high-concurrency environments (Cloudflare Workers, Hono, Node.js), incoming HTTP requests suffer zero latency penalty from graph reconstruction.

2. Microsecond AST Real-Time Type Synthesis (0.04 ms)

During development and Hot Module Replacement (HMR), the plugin's background AST scanner detects file changes and generates types/ignore.modular.d.ts in 0.04 milliseconds:

• Augments the global ModularContainer interface with zero manual boilerplate; • Developers write const { db, logger } = container; and instantly enjoy 100% accurate IDE auto-completion and type checking; • Safely manages ephemeral declaration files with automatic .gitignore self-healing.

3. Clear Host Ignition Boundary

Traditional frameworks force business code to adapt to proprietary application classes and controller decorators. With @path-ioc/unplugin, the host only ignites the container:

Business modules circulate 100% autonomously within the mesh, completely decoupled from the host environment.

Universal Bundler Integration

1. Installation

2. Bundler Configuration Quick Reference

Vite (vite.config.ts)

Rolldown (rolldown.config.ts)

Rspack (rspack.config.js)

Webpack 5 (webpack.config.js)

Rollup (rollup.config.js) & Esbuild

Zero-Configuration by Default: All bundler plugins fully support zero-argument pathIoc() invocation. If your project uses custom directories, override them as needed:

Plugin Options (PathIocPluginOptions)

| Option | Type | Default | Description |

| modulesPath | string | 'src/modules' | Root directory scanned for modular IoC entrypoints (index.ts/tsx). v0.1.7+: Supports targeted multi-module compilation using brace syntax (e.g., src/modules/{core,admin}). To maintain path determinism, wildcards (*, ?) and nested braces are not supported. | | typeFileOutput | string | 'types' | Target directory where ignore.modular.d.ts is generated. |

Virtual Module (virtual:modular-container)

The plugin injects virtual:modular-container into your application at build time:

Serverless / Hono Production Example (Request Isolation)

Module Authoring & Core Runtime Guide

@path-ioc/unplugin focuses on compile-time automated scanning, type synthesis, and single-graph cache injection. For authoring main pure-function closures, declaring Mesh dependencies, and leveraging IoC-DL and AOP aspects, please refer directly to: 👉 Read the @path-ioc/core Architectural & Practical Guide or visit the official documentation at https://path-ioc.dev/.

License

Released under the MIT License. Copyright © 2026-present Path-IoC Organization & Lian HanLin.

Description from the npm listing.