@typed/virtual-modules-vite 1.0.0-beta.1

package/README.md

@@ -0,0 +1,140 @@
+# @typed/virtual-modules-vite
+
+Vite plugin that integrates [@typed/virtual-modules](../virtual-modules) for virtual module resolution and loading in both dev and build. Enables compile-time code generation—imports like `virtual:config` or `api:./routes` resolve to generated TypeScript at build time.
+
+## Install
+
+```bash
+pnpm add @typed/virtual-modules @typed/virtual-modules-vite
+```
+
+Peer: `vite` (>=5).
+
+## Overview
+
+**Virtual modules** are imports that resolve to generated code at dev/build time rather than to files on disk. This plugin plugs the `@typed/virtual-modules` resolver into Vite's `resolveId` and `load` hooks, so any `VirtualModulePlugin` registered with a `PluginManager` can serve content when that module specifier is imported.
+
+- Supports **static** virtual modules (pure code generation from id/importer).
+- Supports **type-aware** virtual modules via the optional TypeInfo API (`api.file()`, `api.directory()` when `createTypeInfoApiSession` is provided).
+
+## Usage
+
+### Basic static virtual module
+
+1. Create a resolver (`PluginManager`) and register your virtual module plugins.
+2. Add the Vite plugin with that resolver.
+
+```ts
+import { defineConfig } from "vite";
+import { PluginManager } from "@typed/virtual-modules";
+import { virtualModulesVitePlugin } from "@typed/virtual-modules-vite";
+
+const manager = new PluginManager([
+  {
+    name: "my-virtual",
+    shouldResolve(id) {
+      return id === "virtual:config";
+    },
+    build(id) {
+      return `export const config = { env: "dev" };`;
+    },
+  },
+]);
+
+export default defineConfig({
+  plugins: [virtualModulesVitePlugin({ resolver: manager })],
+});
+```
+
+Then in app code:
+
+```ts
+import { config } from "virtual:config";
+```
+
+### Type-aware virtual modules
+
+When plugins use the TypeInfo API (e.g. `api.file()`, `api.directory()`) for type-aware code generation, pass `createTypeInfoApiSession` so the resolver can create a session with the project's TypeScript program:
+
+```ts
+import { dirname } from "node:path";
+import ts from "typescript";
+import { createTypeInfoApiSession, PluginManager } from "@typed/virtual-modules";
+import { virtualModulesVitePlugin } from "@typed/virtual-modules-vite";
+
+// Build program from your project (e.g. from tsconfig)
+const program = ts.createProgram(["./src/main.ts"], { /* ... */ });
+
+const createSession = () => createTypeInfoApiSession({ ts, program });
+const manager = new PluginManager([
+  {
+    name: "file-snapshot",
+    shouldResolve(id) {
+      return id === "virtual:file-snapshot";
+    },
+    build(_id, importer, api) {
+      const baseDir = dirname(importer);
+      const result = api.file("types.ts", { baseDir });
+      if (!result.ok) return `export const names = [];`;
+      const names = result.snapshot.exports.map((e) => e.name);
+      return `export const names = ${JSON.stringify(names)};`;
+    },
+  },
+]);
+
+export default defineConfig({
+  plugins: [
+    virtualModulesVitePlugin({
+      resolver: manager,
+      createTypeInfoApiSession: createSession,
+    }),
+  ],
+});
+```
+
+See [@typed/virtual-modules](../virtual-modules) for the full TypeInfo API.
+
+### Integrating with @typed/vite-plugin
+
+If you want router (`virtual:router`) and HttpApi (`api:./<dir>`) virtual modules without wiring this plugin manually, use [@typed/vite-plugin](../vite-plugin). It includes `virtualModulesVitePlugin` and pre-registers the router and HttpApi plugins from [@typed/app](../app):
+
+```ts
+import { defineConfig } from "vite";
+import { typedVitePlugin } from "@typed/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    typedVitePlugin({
+      createTypeInfoApiSession: createSession, // required for router type-checking
+      routerVmOptions: { /* ... */ },
+      apiVmOptions: { /* ... */ }, // optional
+    }),
+  ],
+});
+```
+
+## API
+
+### `virtualModulesVitePlugin(options)`
+
+Returns a Vite plugin. Uses `enforce: "pre"` so virtual resolution runs before other resolvers.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `resolver` | `VirtualModuleResolver` | Resolver (e.g. `PluginManager`) that handles virtual module resolution and loading. |
+| `createTypeInfoApiSession` | `CreateTypeInfoApiSession` | Optional. Session factory for TypeInfo API when plugins use `api.file()` / `api.directory()`. |
+| `warnOnError` | `boolean` | Log resolution/load errors to console (default `true`). Errors include plugin name and message. |
+
+### Encoding helpers
+
+The plugin uses `\0virtual:` + base64url encoding to carry `(id, importer)` through Vite's resolution. Exported for consumers (e.g. URL encoding in dev):
+
+- **`encodeVirtualId(id, importer)`** — Encode a virtual id and importer into the internal format.
+- **`decodeVirtualId(resolvedId)`** — Parse an encoded id; returns `{ id, importer }` or `null` if not a virtual id.
+- **`isVirtualId(resolvedId)`** — Returns `true` if the string is an encoded virtual id.
+
+Payload validation: decoded `id` and `importer` must not contain null bytes, be empty, or exceed 4096 characters.
+
+## Errors
+
+The plugin does **not** throw. When resolution or load fails, `resolveId` / `load` return `null` and the import fails at build/dev (module not found). When `warnOnError` is true (default), errors are logged to `console.warn`. See [virtual-modules-errors-and-gotchas](../virtual-modules/.docs/virtual-modules-errors-and-gotchas.md) for full reference.

package/dist/encodeVirtualId.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Encode (id, importer) into a single string for Vite's resolveId return value.
+ * Uses base64url so path characters (e.g. `:`, `\`) don't break parsing.
+ */
+export declare function encodeVirtualId(id: string, importer: string): string;
+/**
+ * Parse a virtual id produced by encodeVirtualId. Returns null if not a virtual id.
+ */
+export declare function decodeVirtualId(resolvedId: string): {
+    id: string;
+    importer: string;
+} | null;
+export declare function isVirtualId(resolvedId: string): boolean;
+//# sourceMappingURL=encodeVirtualId.d.ts.map

package/dist/encodeVirtualId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encodeVirtualId.d.ts","sourceRoot":"","sources":["../src/encodeVirtualId.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmB3F;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/encodeVirtualId.js

@@ -0,0 +1,41 @@
+const PREFIX = "\0virtual:";
+function toBase64Url(s) {
+    return Buffer.from(s, "utf8").toString("base64url");
+}
+function fromBase64Url(s) {
+    return Buffer.from(s, "base64url").toString("utf8");
+}
+/**
+ * Encode (id, importer) into a single string for Vite's resolveId return value.
+ * Uses base64url so path characters (e.g. `:`, `\`) don't break parsing.
+ */
+export function encodeVirtualId(id, importer) {
+    return `${PREFIX}${toBase64Url(id)}:${toBase64Url(importer)}`;
+}
+/**
+ * Parse a virtual id produced by encodeVirtualId. Returns null if not a virtual id.
+ */
+export function decodeVirtualId(resolvedId) {
+    if (!resolvedId.startsWith(PREFIX)) {
+        return null;
+    }
+    const rest = resolvedId.slice(PREFIX.length);
+    const colonIndex = rest.indexOf(":");
+    if (colonIndex === -1) {
+        return null;
+    }
+    const encodedId = rest.slice(0, colonIndex);
+    const encodedImporter = rest.slice(colonIndex + 1);
+    try {
+        return {
+            id: fromBase64Url(encodedId),
+            importer: fromBase64Url(encodedImporter),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isVirtualId(resolvedId) {
+    return resolvedId.startsWith(PREFIX);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { virtualModulesVitePlugin, type VirtualModulesVitePluginOptions } from "./vitePlugin.js";
+export { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { virtualModulesVitePlugin } from "./vitePlugin.js";
+export { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";

package/dist/vitePlugin.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from "vite";
+import type { CreateTypeInfoApiSession, VirtualModuleResolver } from "@typed/virtual-modules";
+export interface VirtualModulesVitePluginOptions {
+    /**
+     * Resolver that handles virtual module resolution (e.g. a PluginManager instance).
+     */
+    readonly resolver: VirtualModuleResolver;
+    /**
+     * Optional session factory for TypeInfo API when plugins need type information.
+     */
+    readonly createTypeInfoApiSession?: CreateTypeInfoApiSession;
+    /**
+     * When true, resolution errors are logged with console.warn. Default true.
+     */
+    readonly warnOnError?: boolean;
+}
+/**
+ * Vite plugin that integrates @typed/virtual-modules: resolves and loads virtual
+ * modules via the given resolver (e.g. PluginManager) in both dev and build.
+ */
+export declare function virtualModulesVitePlugin(options: VirtualModulesVitePluginOptions): Plugin;
+//# sourceMappingURL=vitePlugin.d.ts.map

package/dist/vitePlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitePlugin.d.ts","sourceRoot":"","sources":["../src/vitePlugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAK9F,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC;;OAEG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IAC7D;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAUD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,MAAM,CAoDzF"}

package/dist/vitePlugin.js

@@ -0,0 +1,62 @@
+import { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";
+const PLUGIN_NAME = "virtual-modules";
+/** Validate decoded id/importer before passing to resolver (defense in depth). */
+function validateDecodedPayload(id, importer) {
+    if (typeof id !== "string" || id.length === 0 || id.includes("\0"))
+        return false;
+    if (typeof importer !== "string" || importer.length === 0 || importer.includes("\0"))
+        return false;
+    if (id.length > 4096 || importer.length > 4096)
+        return false;
+    return true;
+}
+/**
+ * Vite plugin that integrates @typed/virtual-modules: resolves and loads virtual
+ * modules via the given resolver (e.g. PluginManager) in both dev and build.
+ */
+export function virtualModulesVitePlugin(options) {
+    const { resolver, createTypeInfoApiSession, warnOnError = true } = options;
+    return {
+        name: PLUGIN_NAME,
+        enforce: "pre",
+        resolveId(id, importer) {
+            if (!importer) {
+                return null;
+            }
+            const result = resolver.resolveModule({
+                id,
+                importer,
+                createTypeInfoApiSession,
+            });
+            if (result.status === "resolved") {
+                return encodeVirtualId(id, importer);
+            }
+            if (result.status === "error" && warnOnError) {
+                console.warn(`[${PLUGIN_NAME}] ${result.diagnostic.pluginName}: ${result.diagnostic.message}`);
+            }
+            return null;
+        },
+        load(resolvedId) {
+            if (!isVirtualId(resolvedId)) {
+                return null;
+            }
+            const parsed = decodeVirtualId(resolvedId);
+            if (!parsed || !validateDecodedPayload(parsed.id, parsed.importer)) {
+                return null;
+            }
+            const { id, importer } = parsed;
+            const result = resolver.resolveModule({
+                id,
+                importer,
+                createTypeInfoApiSession,
+            });
+            if (result.status === "resolved") {
+                return { code: result.sourceText };
+            }
+            if (result.status === "error" && warnOnError) {
+                console.warn(`[${PLUGIN_NAME}] load ${result.diagnostic.pluginName}: ${result.diagnostic.message}`);
+            }
+            return null;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@typed/virtual-modules-vite",
+  "version": "1.0.0-beta.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "[ -d dist ] || rm -f tsconfig.tsbuildinfo; tsc",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@typed/virtual-modules": "workspace:*"
+  },
+  "devDependencies": {
+    "@typed/virtual-modules": "workspace:*",
+    "@types/node": "^25.3.0",
+    "typescript": "catalog:",
+    "vite": "^7.3.1",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/encodeVirtualId.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";
+
+describe("encodeVirtualId / decodeVirtualId", () => {
+  it("round-trips id and importer", () => {
+    const id = "virtual:config";
+    const importer = "/Users/app/src/main.ts";
+    const encoded = encodeVirtualId(id, importer);
+    expect(isVirtualId(encoded)).toBe(true);
+    const decoded = decodeVirtualId(encoded);
+    expect(decoded).toEqual({ id, importer });
+  });
+
+  it("returns null for non-virtual id", () => {
+    expect(decodeVirtualId("/some/path.ts")).toBeNull();
+    expect(isVirtualId("/some/path.ts")).toBe(false);
+  });
+
+  it("handles Windows-style paths", () => {
+    const id = "virtual:env";
+    const importer = "C:\\Users\\app\\src\\main.ts";
+    const encoded = encodeVirtualId(id, importer);
+    const decoded = decodeVirtualId(encoded);
+    expect(decoded).toEqual({ id, importer });
+  });
+});

package/src/encodeVirtualId.ts

@@ -0,0 +1,45 @@
+const PREFIX = "\0virtual:";
+
+function toBase64Url(s: string): string {
+  return Buffer.from(s, "utf8").toString("base64url");
+}
+
+function fromBase64Url(s: string): string {
+  return Buffer.from(s, "base64url").toString("utf8");
+}
+
+/**
+ * Encode (id, importer) into a single string for Vite's resolveId return value.
+ * Uses base64url so path characters (e.g. `:`, `\`) don't break parsing.
+ */
+export function encodeVirtualId(id: string, importer: string): string {
+  return `${PREFIX}${toBase64Url(id)}:${toBase64Url(importer)}`;
+}
+
+/**
+ * Parse a virtual id produced by encodeVirtualId. Returns null if not a virtual id.
+ */
+export function decodeVirtualId(resolvedId: string): { id: string; importer: string } | null {
+  if (!resolvedId.startsWith(PREFIX)) {
+    return null;
+  }
+  const rest = resolvedId.slice(PREFIX.length);
+  const colonIndex = rest.indexOf(":");
+  if (colonIndex === -1) {
+    return null;
+  }
+  const encodedId = rest.slice(0, colonIndex);
+  const encodedImporter = rest.slice(colonIndex + 1);
+  try {
+    return {
+      id: fromBase64Url(encodedId),
+      importer: fromBase64Url(encodedImporter),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isVirtualId(resolvedId: string): boolean {
+  return resolvedId.startsWith(PREFIX);
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { virtualModulesVitePlugin, type VirtualModulesVitePluginOptions } from "./vitePlugin.js";
+export { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";

package/src/vitePlugin.integration.test.ts

@@ -0,0 +1,224 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import ts from "typescript";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createTypeInfoApiSession,
+  PluginManager,
+  type VirtualModulePlugin,
+} from "@typed/virtual-modules";
+import { createServer } from "vite";
+import { encodeVirtualId } from "./encodeVirtualId.js";
+import { virtualModulesVitePlugin } from "./vitePlugin.js";
+
+const tempDirs: string[] = [];
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "virtual-modules-vite-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+/**
+ * Virtual module that uses TypeInfoApi.file() to read a single file's type snapshot
+ * and exports the list of export names.
+ */
+function fileSnapshotPlugin(): VirtualModulePlugin {
+  return {
+    name: "file-snapshot",
+    shouldResolve(id: string): boolean {
+      return id === "virtual:file-snapshot";
+    },
+    build(_id: string, importer: string, api): string {
+      const baseDir = dirname(importer);
+      const result = api.file("types.ts", { baseDir });
+      if (!result.ok) {
+        return `export const fileExportNames = []; export const fileError = ${JSON.stringify(result.error)};`;
+      }
+      const names = result.snapshot.exports.map((e) => e.name);
+      return `export const fileExportNames = ${JSON.stringify(names)};`;
+    },
+  };
+}
+
+/**
+ * Virtual module that uses TypeInfoApi.directory() to list type snapshots in a directory
+ * and exports the relative file paths.
+ */
+function dirSnapshotPlugin(): VirtualModulePlugin {
+  return {
+    name: "dir-snapshot",
+    shouldResolve(id: string): boolean {
+      return id === "virtual:dir-snapshot";
+    },
+    build(_id: string, importer: string, api): string {
+      const srcDir = dirname(importer);
+      const baseDir = join(srcDir, "features");
+      const snapshots = api.directory("*.ts", {
+        baseDir,
+        recursive: true,
+      });
+      const filePaths = snapshots.map((s) => s.filePath);
+      return `export const dirFilePaths = ${JSON.stringify(filePaths)};`;
+    },
+  };
+}
+
+describe("virtualModulesVitePlugin integration", () => {
+  it("serves virtual module content in dev (static virtual module)", async () => {
+    const projectRoot = createTempDir();
+    const srcDir = join(projectRoot, "src");
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(projectRoot, "index.html"),
+      `<!DOCTYPE html><html><body><script type="module" src="/src/main.ts"></script></body></html>`,
+      "utf8",
+    );
+    writeFileSync(
+      join(srcDir, "main.ts"),
+      'import { value } from "virtual:static";\nexport const out = value;',
+      "utf8",
+    );
+    const manager = new PluginManager([
+      {
+        name: "static",
+        shouldResolve: (id) => id === "virtual:static",
+        build: () => 'export const value = "from-virtual";',
+      },
+    ]);
+    const server = await createServer({
+      root: projectRoot,
+      plugins: [virtualModulesVitePlugin({ resolver: manager })],
+      server: { port: 0 },
+      logLevel: "warn",
+    });
+    await server.listen();
+    try {
+      const base = `http://localhost:${server.config.server.port}`;
+      const mainRes = await fetch(`${base}/src/main.ts`);
+      expect(mainRes.ok).toBe(true);
+      const mainText = await mainRes.text();
+      expect(mainText).toContain("out");
+      const importer = join(projectRoot, "src", "main.ts");
+      const resolvedId = encodeVirtualId("virtual:static", importer);
+      const virtualPath = "/@id/" + resolvedId.split(String.fromCharCode(0)).join("__x00__");
+      const virtualRes = await fetch(base + virtualPath);
+      expect(virtualRes.ok).toBe(true);
+      const virtualText = await virtualRes.text();
+      expect(virtualText).toContain("from-virtual");
+      await server.waitForRequestsIdle();
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("serves virtual modules backed by api.file() and api.directory() in dev", async () => {
+    const projectRoot = createTempDir();
+    const srcDir = join(projectRoot, "src");
+    const featuresDir = join(projectRoot, "src", "features");
+    mkdirSync(featuresDir, { recursive: true });
+
+    writeFileSync(
+      join(projectRoot, "index.html"),
+      `<!DOCTYPE html><html><head><meta charset="utf-8"/></head><body><script type="module" src="/src/main.ts"></script></body></html>`,
+      "utf8",
+    );
+    writeFileSync(
+      join(projectRoot, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: {
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          strict: true,
+          skipLibCheck: true,
+        },
+        include: ["src"],
+      }),
+      "utf8",
+    );
+    writeFileSync(join(srcDir, "types.ts"), `export type X = string; export const y = 42;`, "utf8");
+    writeFileSync(
+      join(srcDir, "main.ts"),
+      [
+        'import { fileExportNames } from "virtual:file-snapshot";',
+        'import { dirFilePaths } from "virtual:dir-snapshot";',
+        "export const fileExportNamesFromFile = fileExportNames;",
+        "export const dirFilePathsFromDir = dirFilePaths;",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(join(featuresDir, "one.ts"), `export const one = "one";`, "utf8");
+    writeFileSync(join(featuresDir, "two.ts"), `export const two = "two";`, "utf8");
+
+    const rootFiles = [
+      join(srcDir, "main.ts"),
+      join(srcDir, "types.ts"),
+      join(featuresDir, "one.ts"),
+      join(featuresDir, "two.ts"),
+    ];
+    const program = ts.createProgram(rootFiles, {
+      strict: true,
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      skipLibCheck: true,
+      noEmit: true,
+    });
+
+    const createSession = () => createTypeInfoApiSession({ ts, program });
+    const manager = new PluginManager([fileSnapshotPlugin(), dirSnapshotPlugin()]);
+
+    const server = await createServer({
+      root: projectRoot,
+      plugins: [
+        virtualModulesVitePlugin({
+          resolver: manager,
+          createTypeInfoApiSession: createSession,
+          warnOnError: true,
+        }),
+      ],
+      server: { port: 0 },
+      logLevel: "warn",
+    });
+    await server.listen();
+    try {
+      const base = `http://localhost:${server.config.server.port}`;
+      const mainRes = await fetch(`${base}/src/main.ts`);
+      expect(mainRes.ok).toBe(true);
+      const mainText = await mainRes.text();
+      expect(mainText).toContain("fileExportNamesFromFile");
+      expect(mainText).toContain("dirFilePathsFromDir");
+      const importer = join(projectRoot, "src", "main.ts");
+      const fileResolvedId = encodeVirtualId("virtual:file-snapshot", importer);
+      const dirResolvedId = encodeVirtualId("virtual:dir-snapshot", importer);
+      const toUrl = (id: string) =>
+        base + "/@id/" + id.split(String.fromCharCode(0)).join("__x00__");
+      const fileSnapshotRes = await fetch(toUrl(fileResolvedId));
+      expect(fileSnapshotRes.ok).toBe(true);
+      const fileSnapshotText = await fileSnapshotRes.text();
+      expect(fileSnapshotText).toContain("fileExportNames");
+      expect(fileSnapshotText).toMatch(/"X".*"y"/);
+
+      const dirSnapshotRes = await fetch(toUrl(dirResolvedId));
+      expect(dirSnapshotRes.ok).toBe(true);
+      const dirSnapshotText = await dirSnapshotRes.text();
+      expect(dirSnapshotText).toContain("dirFilePaths");
+      expect(dirSnapshotText).toContain("one.ts");
+      expect(dirSnapshotText).toContain("two.ts");
+      await server.waitForRequestsIdle();
+    } finally {
+      await server.close();
+    }
+  });
+});

package/src/vitePlugin.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { PluginManager } from "@typed/virtual-modules";
+import { virtualModulesVitePlugin } from "./vitePlugin.js";
+
+type ResolveId = (specifier: string, importer: string | undefined) => string | null;
+type Load = (specifier: string) => string | { code: string } | null;
+
+describe("virtualModulesVitePlugin", () => {
+  it("returns a plugin with name and enforce pre", () => {
+    const manager = new PluginManager();
+    const plugin = virtualModulesVitePlugin({ resolver: manager });
+    expect(plugin.name).toBe("virtual-modules");
+    expect(plugin.enforce).toBe("pre");
+  });
+
+  it("resolveId returns null when importer is undefined", () => {
+    const manager = new PluginManager([
+      {
+        name: "test",
+        shouldResolve: () => true,
+        build: () => "export {};",
+      },
+    ]);
+    const plugin = virtualModulesVitePlugin({ resolver: manager });
+    const resolveId = plugin.resolveId! as ResolveId;
+    expect(resolveId("virtual:x", undefined)).toBeNull();
+  });
+
+  it("resolveId returns encoded id when resolver resolves", () => {
+    const manager = new PluginManager([
+      {
+        name: "test",
+        shouldResolve: (id) => id === "virtual:config",
+        build: () => "export const x = 1;",
+      },
+    ]);
+    const plugin = virtualModulesVitePlugin({ resolver: manager });
+    const resolveId = plugin.resolveId! as ResolveId;
+    const out = resolveId("virtual:config", "/app/main.ts");
+    expect(out).not.toBeNull();
+    expect(typeof out).toBe("string");
+    expect((out as string).startsWith("\0virtual:")).toBe(true);
+  });
+
+  it("load returns sourceText for encoded virtual id", () => {
+    const manager = new PluginManager([
+      {
+        name: "test",
+        shouldResolve: (id) => id === "virtual:config",
+        build: () => "export const x = 1;",
+      },
+    ]);
+    const plugin = virtualModulesVitePlugin({ resolver: manager });
+    const resolveId = plugin.resolveId! as ResolveId;
+    const load = plugin.load! as Load;
+    const resolvedId = resolveId("virtual:config", "/app/main.ts") as string;
+    const result = load(resolvedId);
+    const code = typeof result === "string" ? result : result?.code;
+    expect(code).toBe("export const x = 1;");
+  });
+});

package/src/vitePlugin.ts

@@ -0,0 +1,86 @@
+import type { Plugin } from "vite";
+import type { CreateTypeInfoApiSession, VirtualModuleResolver } from "@typed/virtual-modules";
+import { encodeVirtualId, decodeVirtualId, isVirtualId } from "./encodeVirtualId.js";
+
+const PLUGIN_NAME = "virtual-modules";
+
+export interface VirtualModulesVitePluginOptions {
+  /**
+   * Resolver that handles virtual module resolution (e.g. a PluginManager instance).
+   */
+  readonly resolver: VirtualModuleResolver;
+  /**
+   * Optional session factory for TypeInfo API when plugins need type information.
+   */
+  readonly createTypeInfoApiSession?: CreateTypeInfoApiSession;
+  /**
+   * When true, resolution errors are logged with console.warn. Default true.
+   */
+  readonly warnOnError?: boolean;
+}
+
+/** Validate decoded id/importer before passing to resolver (defense in depth). */
+function validateDecodedPayload(id: string, importer: string): boolean {
+  if (typeof id !== "string" || id.length === 0 || id.includes("\0")) return false;
+  if (typeof importer !== "string" || importer.length === 0 || importer.includes("\0")) return false;
+  if (id.length > 4096 || importer.length > 4096) return false;
+  return true;
+}
+
+/**
+ * Vite plugin that integrates @typed/virtual-modules: resolves and loads virtual
+ * modules via the given resolver (e.g. PluginManager) in both dev and build.
+ */
+export function virtualModulesVitePlugin(options: VirtualModulesVitePluginOptions): Plugin {
+  const { resolver, createTypeInfoApiSession, warnOnError = true } = options;
+
+  return {
+    name: PLUGIN_NAME,
+    enforce: "pre",
+
+    resolveId(id: string, importer: string | undefined): string | null {
+      if (!importer) {
+        return null;
+      }
+      const result = resolver.resolveModule({
+        id,
+        importer,
+        createTypeInfoApiSession,
+      });
+      if (result.status === "resolved") {
+        return encodeVirtualId(id, importer);
+      }
+      if (result.status === "error" && warnOnError) {
+        console.warn(
+          `[${PLUGIN_NAME}] ${result.diagnostic.pluginName}: ${result.diagnostic.message}`,
+        );
+      }
+      return null;
+    },
+
+    load(resolvedId: string): string | { code: string } | null {
+      if (!isVirtualId(resolvedId)) {
+        return null;
+      }
+      const parsed = decodeVirtualId(resolvedId);
+      if (!parsed || !validateDecodedPayload(parsed.id, parsed.importer)) {
+        return null;
+      }
+      const { id, importer } = parsed;
+      const result = resolver.resolveModule({
+        id,
+        importer,
+        createTypeInfoApiSession,
+      });
+      if (result.status === "resolved") {
+        return { code: result.sourceText };
+      }
+      if (result.status === "error" && warnOnError) {
+        console.warn(
+          `[${PLUGIN_NAME}] load ${result.diagnostic.pluginName}: ${result.diagnostic.message}`,
+        );
+      }
+      return null;
+    },
+  };
+}