💡 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)

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:

import { createModularContainer } from "virtual:modular-container";

// One-line host ignition (Hono, Express, Koa, Workers, Next.js API, CLI)
const container = await createModularContainer();

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

Universal Bundler Integration

1. Installation

pnpm add -D @path-ioc/unplugin
pnpm add @path-ioc/core

2. Bundler Configuration Quick Reference

Vite (vite.config.ts)

import { defineConfig } from "vite";
import { vitePlugin as pathIoc } from "@path-ioc/unplugin";

export default defineConfig({
  plugins: [pathIoc()],
});

Rolldown (rolldown.config.ts)

import { defineConfig } from "rolldown";
import { rolldownPlugin as pathIoc } from "@path-ioc/unplugin";

export default defineConfig({
  plugins: [pathIoc()],
});

Rspack (rspack.config.js)

const { rspackPlugin: pathIoc } = require("@path-ioc/unplugin");

module.exports = {
  plugins: [pathIoc()],
};

Webpack 5 (webpack.config.js)

const { webpackPlugin: pathIoc } = require("@path-ioc/unplugin");

module.exports = {
  plugins: [pathIoc()],
};

Rollup (rollup.config.js) & Esbuild

// Rollup
import { rollupPlugin as pathIoc } from "@path-ioc/unplugin";

// Esbuild
import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";

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

pathIoc({
  modulesPath: "src/modules", // Custom module root directory (default: "src/modules")
  typeFileOutput: "types", // Custom type declaration output directory (default: "types")
});

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:

import {
  modules, // Complete module descriptor array: { key: string, module: IOCModule }[]
  createModularContainer, // High-performance container bootstrapper: (targetContainer?: Record<string, any>) => Promise<ModularContainer>
} from "virtual:modular-container";

Serverless / Hono Production Example (Request Isolation)

import { Hono } from "hono";
import { createModularContainer } from "virtual:modular-container";

const app = new Hono();

// Wildcard Gateway: Entry defines zero business routes; delegates to container aggregator
app.all("*", async (c) => {
  // 1. Single-graph cache reuses compiled DAG: hydrates request-isolated container in ~21.2µs
  // 2. Pass per-request context directly as container seed
  const container = await createModularContainer({ requestContext: c });
  return await container.apiAggregator();
});

export default app;

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.