@vercube/vite 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present - Vercube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @vercube/vite
+
+Run a [Vercube](https://github.com/vercube/vercube) server as a [Vite](https://vite.dev) plugin, built on Vite's [Environment API](https://vite.dev/guide/api-environment.html). Your decorator-based controllers run inside an isolated dev worker with fast server-side HMR, and `vite build` produces a runnable server bundle, all with zero-config controller discovery.
+
+> **Experimental.** This integration is in an early stage and its API may change between releases.
+
+## Installation
+
+```bash
+pnpm add -D @vercube/vite vite
+```
+
+`experimentalDecorators` must be enabled in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false
+  }
+}
+```
+
+## Usage
+
+Add the plugin to your `vite.config.ts`:
+
+```ts
+import { vercube } from '@vercube/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [vercube()],
+});
+```
+
+Place a `@Controller` anywhere under `src/`. It is discovered automatically, with no manual registration:
+
+```ts
+// src/Controllers/HelloController.ts
+import { Controller, Get, Param } from '@vercube/core';
+
+@Controller('/api/hello')
+export default class HelloController {
+  @Get('/')
+  index() {
+    return { message: 'Hello from Vercube + Vite!' };
+  }
+
+  @Get('/:name')
+  greet(@Param('name') name: string) {
+    return { message: `Hello, ${name}!` };
+  }
+}
+```
+
+Then:
+
+```bash
+vite          # dev server with HMR
+vite build    # bundles to dist/index.mjs
+node dist/index.mjs   # runs the built server
+```
+
+## How it works
+
+- A dedicated Vite **environment** (`vercube`) runs the server. In dev it executes inside an isolated [`env-runner`](https://www.npmjs.com/package/env-runner) worker via Vite's `ModuleRunner`.
+- Controllers and `@Injectable` services are discovered by scanning your source tree (AST parsing via [`@vercube/scan`](../scan)) and assembled into a generated entry that creates the app, binds the classes, and exports `fetch`.
+- Vercube only claims **the routes you actually define**. Requests matching a discovered route are handed to the worker, everything else falls through to Vite. So the plugin sits next to a frontend (Vue, React, plain JS) that Vite serves on the same server. See [`examples/vite`](../../examples/vite) for a Vite + Vue app calling a Vercube API.
+- Editing or adding controllers triggers a worker reload, so changes are live without a manual restart.
+
+`vite build` builds your frontend (if any) and then bundles the Vercube server to `dist/index.mjs`.
+
+## Options
+
+| Option      | Type       | Default         | Description                                                                                                       |
+| ----------- | ---------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `rootDir`   | `string`   | Vite `root`     | Project root used to resolve `scanDirs` and `setupFile`.                                                          |
+| `scanDirs`  | `string[]` | `['src']`       | Directories scanned (recursively) for `@Controller` and `@Injectable` classes.                                    |
+| `setupFile` | `string`   | `undefined`     | Module whose default export `(app: App) => void \| Promise<void>` runs as `createApp`'s setup hook (before init). |
+| `runner`    | `string`   | `'node-worker'` | The `env-runner` runner used to execute server code in dev.                                                       |
+
+## Setup file
+
+Auto-discovery binds `@Controller` and `@Injectable` classes. Anything it can't infer, such as registering plugins, mounting storage, or binding an interface to an implementation, goes in a `setupFile`. It runs as `createApp`'s `setup` hook, **before** the app initializes, so it is early enough to register plugins:
+
+```ts
+import { vercube } from '@vercube/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [vercube({ setupFile: './src/Boot/Setup.ts' })],
+});
+```
+
+```ts
+// src/Boot/Setup.ts
+import type { App } from '@vercube/core';
+import { StorageManager } from '@vercube/storage';
+import { MemoryStorage } from '@vercube/storage/drivers/MemoryStorage';
+
+export default async function setup(app: App) {
+  app.container.bind(StorageManager);
+  app.container.get(StorageManager).mount({ storage: MemoryStorage });
+}
+```
+
+## WebSockets
+
+The `@vercube/ws` plugin works in both the dev server and the production build. Register it from your `setupFile` (`app.addPlugin(WebsocketPlugin)`) and define WebSocket controllers as usual (`@Controller` + `@Namespace`). They are auto-discovered. The dev server forwards upgrade handshakes into the worker, and the production server handles them natively through `srvx`.
+
+## License
+
+MIT

package/dist/context-CfzvWZrR.mjs

@@ -0,0 +1,117 @@
+import { dirname, isAbsolute, resolve } from "pathe";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { scanSource } from "@vercube/scan";
+//#region src/entry.ts
+/**
+* Generates the source of the server entry module.
+*
+* The module creates a Vercube app, binds every auto-discovered controller and
+* service into its DI container, runs the optional setup file, flushes the
+* container queue (which registers routes via decorator initialization), and
+* exports the app's `fetch` handler. Imports and binds are deduplicated by class
+* name.
+*
+* The entry is written to a real file rather than served as a `\0`-virtual
+* module: Vite resolves bare imports from virtual modules inconsistently with
+* those from project files, which would load framework packages twice and break
+* Vercube's class-reference DI tokens. A real on-disk module resolves its
+* imports the same way the controllers do, keeping a single instance of each.
+*
+* @param ctx - The plugin context holding discovered controllers/services.
+* @returns The generated module source.
+*/
+function generateServerEntry(ctx) {
+	const discovered = [...ctx.controllers, ...ctx.services];
+	const imports = /* @__PURE__ */ new Map();
+	for (const entry of discovered) if (!imports.has(entry.importClassName)) imports.set(entry.importClassName, entry.import);
+	const lines = [ctx.hasClient ? `import { createApp, HttpServer, serveStaticFiles } from '@vercube/core';` : `import { createApp } from '@vercube/core';`];
+	if (ctx.hasClient) lines.push(`import { fileURLToPath } from 'node:url';`);
+	if (ctx.setupFile) lines.push(`import __vercubeSetup__ from ${JSON.stringify(ctx.setupFile)};`);
+	lines.push(...imports.values(), "");
+	const setupBody = [];
+	if (ctx.setupFile) setupBody.push("  await __vercubeSetup__(app);");
+	if (ctx.hasClient) setupBody.push("  if (import.meta.main) {", "    const dir = fileURLToPath(new URL('./public', import.meta.url));", "    app.container.get(HttpServer).addPlugin(serveStaticFiles(dir));", "  }");
+	if (setupBody.length > 0) lines.push("const app = await createApp({ setup: async (app) => {", ...setupBody, "} });", "");
+	else lines.push("const app = await createApp();", "");
+	lines.push(...[...imports.keys()].map((name) => `app.container.bind(${name});`), "");
+	lines.push("app.container.flushQueue();", "");
+	lines.push("if (import.meta.main) {", "  await app.listen();", "}", "");
+	lines.push("export const fetch = app.fetch.bind(app);", "");
+	lines.push("export const handleUpgrade = (req, socket, head) => globalThis.__vercube_ws_upgrade__?.(req, socket, head);", "");
+	return lines.join("\n");
+}
+/**
+* Writes the generated server entry to {@link VercubePluginContext.serverEntry},
+* creating the parent directory if needed.
+*
+* @param ctx - The plugin context.
+*/
+function writeServerEntry(ctx) {
+	mkdirSync(dirname(ctx.serverEntry), { recursive: true });
+	writeFileSync(ctx.serverEntry, generateServerEntry(ctx), "utf8");
+}
+//#endregion
+//#region src/context.ts
+const DEFAULT_SCAN_DIRS = ["src"];
+/** Location of the generated server entry, kept inside node_modules so it stays out of source control and file watchers. */
+const SERVER_ENTRY_REL = "node_modules/.vercube/server-entry.mjs";
+/** Build output directory (relative to root) for the frontend client, served by the built server in production. */
+const CLIENT_OUT_DIR = "dist/public";
+/**
+* Creates the initial plugin context from user configuration. Directories are
+* left unresolved until {@link setupContext}, which has access to Vite's root.
+*
+* @param pluginConfig - The user-provided plugin configuration.
+* @returns A fresh, uninitialized plugin context.
+*/
+function createContext(pluginConfig) {
+	const root = pluginConfig.rootDir ?? process.cwd();
+	return {
+		pluginConfig,
+		root,
+		scanDirs: [],
+		serverEntry: resolve(root, SERVER_ENTRY_REL),
+		dev: true,
+		hasClient: false,
+		controllers: [],
+		routes: [],
+		services: []
+	};
+}
+/**
+* Resolves the project root, scan directories and setup file against Vite's
+* configuration, runs an initial source scan, and writes the server entry.
+*
+* @param ctx - The plugin context to populate.
+* @param options - Resolution inputs derived from Vite's config.
+*/
+async function setupContext(ctx, options) {
+	ctx.root = ctx.pluginConfig.rootDir ? resolveFrom(options.root, ctx.pluginConfig.rootDir) : options.root;
+	ctx.dev = options.dev;
+	ctx.serverEntry = resolve(ctx.root, SERVER_ENTRY_REL);
+	ctx.hasClient = existsSync(resolve(ctx.root, "index.html"));
+	ctx.scanDirs = (ctx.pluginConfig.scanDirs ?? DEFAULT_SCAN_DIRS).map((dir) => resolveFrom(ctx.root, dir));
+	ctx.setupFile = ctx.pluginConfig.setupFile ? resolveFrom(ctx.root, ctx.pluginConfig.setupFile) : void 0;
+	await scanProject(ctx);
+}
+/**
+* Re-scans the project source for controllers and services, then rewrites the
+* server entry. Called on startup and whenever watched scan directories change.
+*
+* @param ctx - The plugin context to refresh.
+*/
+async function scanProject(ctx) {
+	const { controllers, routes, services } = await scanSource({ dirs: ctx.scanDirs });
+	ctx.controllers = controllers;
+	ctx.routes = routes;
+	ctx.services = services;
+	writeServerEntry(ctx);
+}
+/**
+* Resolves `target` against `base` when it is relative, leaving absolute paths untouched.
+*/
+function resolveFrom(base, target) {
+	return isAbsolute(target) ? target : resolve(base, target);
+}
+//#endregion
+export { setupContext as i, createContext as n, scanProject as r, CLIENT_OUT_DIR as t };

package/dist/dev-Bl0akm-q.mjs

@@ -0,0 +1,157 @@
+import { r as scanProject } from "./context-CfzvWZrR.mjs";
+import { t as VERCUBE_ENV } from "./types-Cpd32Lkt.mjs";
+import { createViteHotChannel } from "env-runner/vite";
+import { watch } from "chokidar";
+import { addRoute, createRouter, findRoute } from "rou3";
+import { NodeRequest, sendNodeResponse } from "srvx/node";
+import { DevEnvironment } from "vite";
+//#region src/dev.ts
+/** Chokidar events that imply a controller/service was added or removed. */
+const RELOAD_EVENTS = /* @__PURE__ */ new Set([
+	"add",
+	"addDir",
+	"unlink",
+	"unlinkDir"
+]);
+/**
+* Creates a {@link FetchableDevEnvironment} wired to the env-runner worker via a
+* Vite hot channel.
+*
+* @param name - The environment name.
+* @param config - The resolved Vite config.
+* @param devServer - The env-runner manager driving the worker.
+* @param entry - The dev entry the worker should import for this environment.
+* @returns The fetchable dev environment.
+*/
+function createFetchableDevEnvironment(name, config, devServer, entry) {
+	return new FetchableDevEnvironment(name, config, {
+		hot: true,
+		transport: createViteHotChannel(devServer, name)
+	}, devServer, entry);
+}
+/**
+* A Vite `DevEnvironment` that can dispatch HTTP requests into the server code
+* running inside the env-runner worker. On `init` it tells the worker which
+* entry module backs this environment.
+*/
+var FetchableDevEnvironment = class extends DevEnvironment {
+	devServer;
+	#entry;
+	constructor(name, config, context, devServer, entry) {
+		super(name, config, context);
+		this.devServer = devServer;
+		this.#entry = entry;
+	}
+	/**
+	* Dispatches a web `Request` into the worker and resolves with its `Response`.
+	*
+	* @param request - The incoming request.
+	* @returns The server response.
+	*/
+	async dispatchFetch(request) {
+		return this.devServer.fetch(request);
+	}
+	async init(...args) {
+		await this.devServer.init?.();
+		await super.init(...args);
+		this.devServer.sendMessage({
+			type: "custom",
+			event: "vercube:vite-env",
+			data: {
+				name: this.name,
+				entry: this.#entry
+			}
+		});
+	}
+};
+/**
+* Wires the Vercube environment into a Vite dev server: forwards HTTP requests
+* into the worker and watches the scan directories so added/removed controllers
+* are re-discovered without a manual restart.
+*
+* The request middleware is installed eagerly (before Vite's own middlewares)
+* so matched API routes are claimed ahead of Vite's SPA/HTML fallback; every
+* other request falls through to Vite.
+*
+* @param ctx - The shared plugin context.
+* @param server - The Vite dev server.
+*/
+async function configureViteDevServer(ctx, server) {
+	const env = server.environments[VERCUBE_ENV];
+	let matchesRoute = buildRouteMatcher(ctx.routes);
+	const reload = debounce(async () => {
+		await scanProject(ctx);
+		matchesRoute = buildRouteMatcher(ctx.routes);
+		env.moduleGraph.invalidateAll();
+		env.hot.send({ type: "full-reload" });
+	});
+	const watcher = watch(ctx.scanDirs, { ignoreInitial: true }).on("all", (event) => {
+		if (RELOAD_EVENTS.has(event)) reload();
+	});
+	server.httpServer?.once("close", () => {
+		watcher.close();
+		ctx._envRunner?.close();
+	});
+	server.httpServer?.on("upgrade", (req, socket, head) => {
+		const protocol = req.headers["sec-websocket-protocol"];
+		if (typeof protocol === "string" && protocol.startsWith("vite-")) return;
+		ctx._envRunner?.upgrade?.({ node: {
+			req,
+			socket,
+			head
+		} });
+	});
+	const middleware = async (nodeReq, nodeRes, next) => {
+		if (!nodeReq.url || !matchesRoute(nodeReq.url)) return next();
+		try {
+			const request = new NodeRequest({
+				req: nodeReq,
+				res: nodeRes
+			});
+			const response = await env.dispatchFetch(request);
+			if (nodeRes.writableEnded || nodeRes.headersSent) return;
+			await sendNodeResponse(nodeRes, response);
+		} catch (error) {
+			next(error);
+		}
+	};
+	server.middlewares.use(middleware);
+}
+/**
+* Builds a predicate that tells whether a request URL matches any discovered
+* Vercube route, using the same `rou3` router the framework uses at runtime so
+* params (`:id`) and wildcards (`**`) match identically. Matching is
+* method-agnostic: every method (and CORS preflight) for a defined path is
+* Vercube's, so it can answer `405`/`OPTIONS` itself.
+*
+* @param routes - The discovered HTTP routes.
+* @returns A predicate `(url) => boolean`.
+*/
+function buildRouteMatcher(routes) {
+	const router = createRouter();
+	const seen = /* @__PURE__ */ new Set();
+	for (const { route } of routes) {
+		if (seen.has(route)) continue;
+		seen.add(route);
+		addRoute(router, "ANY", route, true);
+	}
+	return (url) => {
+		return findRoute(router, "ANY", url.split(/[?#]/, 1)[0].replace(/\/+$/, "") || "/") !== void 0;
+	};
+}
+/**
+* Minimal trailing debounce: coalesces bursts of file events into a single
+* reload on the next tick.
+*/
+function debounce(fn, delay = 50) {
+	let timer;
+	return () => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = void 0;
+			fn();
+		}, delay);
+	};
+}
+//#endregion
+export { configureViteDevServer, createFetchableDevEnvironment };

package/dist/index.d.mts

@@ -0,0 +1,90 @@
+import { RouteInfo, ServiceInfo } from "@vercube/scan";
+import { RunnerManager } from "env-runner";
+import { Plugin } from "vite";
+
+//#region src/types.d.ts
+/**
+ * The Vite environment name under which the Vercube server runs.
+ */
+declare const VERCUBE_ENV = "vercube";
+/**
+ * User-facing configuration for the Vercube Vite plugin.
+ */
+interface VercubePluginConfig {
+  /**
+   * Project root. Defaults to Vite's resolved `root`.
+   */
+  rootDir?: string;
+  /**
+   * Directories (relative to `rootDir`) whose file trees are scanned for
+   * controllers, `@Injectable` services and middleware. Defaults to `['src']`.
+   */
+  scanDirs?: string[];
+  /**
+   * Path (relative to `rootDir`) to a module whose default export is
+   * `(app: App) => void | Promise<void>`. Runs after auto-discovered classes are
+   * bound but before the container queue is flushed — use it to mount storage,
+   * bind tokens, configure the logger, or register plugins that auto-discovery
+   * cannot infer.
+   */
+  setupFile?: string;
+  /**
+   * The runner used to execute server code in the dev environment.
+   * Defaults to `node-worker`.
+   */
+  runner?: string;
+}
+/**
+ * Internal plugin context shared across the plugin's sub-plugins and hooks.
+ */
+interface VercubePluginContext {
+  /** The resolved user configuration. */
+  pluginConfig: VercubePluginConfig;
+  /** Absolute project root. */
+  root: string;
+  /** Absolute directories scanned for decorated classes. */
+  scanDirs: string[];
+  /** Absolute path to the setup file, if configured. */
+  setupFile?: string;
+  /** Absolute path of the generated server entry module loaded by the worker. */
+  serverEntry: string;
+  /** Whether the plugin is running in dev (serve) mode. */
+  dev: boolean;
+  /** Whether the project has a frontend (`index.html`) the built server should serve. */
+  hasClient: boolean;
+  /** Discovered `@Controller` classes (every controller, including WebSocket-only ones). */
+  controllers: ServiceInfo[];
+  /** Discovered HTTP routes (method + path), used to decide which requests Vercube handles. */
+  routes: RouteInfo[];
+  /** Discovered injectable services (deduplicated against controllers). */
+  services: ServiceInfo[];
+  /** The env-runner manager driving the dev worker. */
+  _envRunner?: RunnerManager;
+  /** Guards concurrent env-runner initialization. */
+  _initPromise?: Promise<RunnerManager>;
+  /** Maps each Vite environment name to the entry the worker should load. */
+  _viteEnvs?: Map<string, string>;
+}
+declare module 'vite' {
+  interface UserConfig {
+    /** Vercube plugin configuration, mergeable from `vite.config.ts`. */
+    vercube?: VercubePluginConfig;
+  }
+}
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The Vercube Vite plugin.
+ *
+ * Runs a Vercube server inside a dedicated Vite environment via the Environment
+ * API: controllers and services are auto-discovered from the project source,
+ * assembled into a generated virtual entry, and executed in an isolated
+ * env-runner worker with HMR. HTTP requests hitting the Vite dev server are
+ * forwarded into that worker.
+ *
+ * @param pluginConfig - Optional plugin configuration.
+ * @returns The array of Vite plugins composing the integration.
+ */
+declare function vercube(pluginConfig?: VercubePluginConfig): Plugin[];
+//#endregion
+export { VERCUBE_ENV, type VercubePluginConfig, type VercubePluginContext, vercube };

package/dist/index.mjs

@@ -0,0 +1,190 @@
+import { i as setupContext, n as createContext, t as CLIENT_OUT_DIR } from "./context-CfzvWZrR.mjs";
+import { t as VERCUBE_ENV } from "./types-Cpd32Lkt.mjs";
+import { defu } from "defu";
+import { dirname, isAbsolute, resolve } from "pathe";
+import { RunnerManager, loadRunner } from "env-runner";
+import { fileURLToPath } from "node:url";
+/**
+* Absolute path to the worker bootstrap loaded by env-runner.
+*/
+const devWorker = resolve(resolve(dirname(fileURLToPath(import.meta.url)), "runtime"), "dev-worker.mjs");
+//#endregion
+//#region src/env.ts
+/**
+* Dev-only `resolve.noExternal` patterns. Only `@vercube/*` must stay in Vite's
+* module graph so class-reference DI tokens are not duplicated; other deps (e.g.
+* CJS-only `dotenv`) are left external and loaded via native `import()`.
+*/
+const DEV_NO_EXTERNAL = [/^@vercube\//];
+/**
+* The custom message event used to tell the worker which entry an environment loads.
+*/
+const VITE_ENV_EVENT = "vercube:vite-env";
+/**
+* Builds the Vite environment options for the Vercube server environment.
+*
+* In dev, `createEnvironment` returns a {@link FetchableDevEnvironment} backed by
+* the env-runner worker. In build, the environment bundles the virtual server
+* entry (wired up in the production milestone).
+*
+* @param ctx - The shared plugin context.
+* @returns The environment options for the `vercube` environment.
+*/
+function createVercubeEnvironment(ctx) {
+	return {
+		consumer: "server",
+		resolve: ctx.dev ? { noExternal: DEV_NO_EXTERNAL } : {},
+		build: {
+			outDir: resolve(ctx.root, "dist"),
+			emptyOutDir: false,
+			copyPublicDir: false,
+			rollupOptions: {
+				input: { index: ctx.serverEntry },
+				external: isBareSpecifier,
+				output: {
+					entryFileNames: "[name].mjs",
+					chunkFileNames: "[name]-[hash].mjs",
+					format: "es"
+				}
+			}
+		},
+		dev: { createEnvironment: async (envName, envConfig) => {
+			const { createFetchableDevEnvironment } = await import("./dev-Bl0akm-q.mjs");
+			const env = createFetchableDevEnvironment(envName, envConfig, getEnvRunner(ctx), ctx.serverEntry);
+			(ctx._viteEnvs ??= /* @__PURE__ */ new Map()).set(envName, ctx.serverEntry);
+			return env;
+		} }
+	};
+}
+/**
+* Initializes the env-runner manager that drives the dev worker. Idempotent and
+* concurrency-safe: repeated calls return the same manager. On unexpected worker
+* exit the runner is reloaded up to three times before giving up.
+*
+* @param ctx - The shared plugin context.
+* @returns The initialized runner manager.
+*/
+async function initEnvRunner(ctx) {
+	if (ctx._envRunner) return ctx._envRunner;
+	if (!ctx._initPromise) ctx._initPromise = (async () => {
+		const manager = new RunnerManager();
+		let retries = 0;
+		manager.onClose((_runner, cause) => {
+			if (retries++ < 3) loadRunnerInto(ctx, manager);
+			else console.error("[vercube] env runner failed after 3 retries.", cause ? `Last cause: ${cause}` : "");
+		});
+		manager.onReady(() => {
+			retries = 0;
+			if (ctx._viteEnvs) for (const [name, entry] of ctx._viteEnvs) manager.sendMessage({
+				type: "custom",
+				event: VITE_ENV_EVENT,
+				data: {
+					name,
+					entry
+				}
+			});
+		});
+		await loadRunnerInto(ctx, manager);
+		ctx._envRunner = manager;
+		return manager;
+	})().finally(() => {
+		ctx._initPromise = void 0;
+	});
+	return ctx._initPromise;
+}
+/**
+* Returns the initialized runner manager, throwing if {@link initEnvRunner} has not run.
+*
+* @param ctx - The shared plugin context.
+* @returns The runner manager.
+*/
+function getEnvRunner(ctx) {
+	if (!ctx._envRunner) throw new Error("[vercube] Env runner not initialized. Call initEnvRunner() first.");
+	return ctx._envRunner;
+}
+/**
+* Returns true for bare module specifiers (npm/workspace packages), which the
+* production build externalizes. Relative paths, absolute paths and virtual
+* (`\0`-prefixed) ids are bundled.
+*
+* @param id - The import specifier to classify.
+* @returns Whether the specifier is a bare dependency.
+*/
+function isBareSpecifier(id) {
+	if (id.startsWith("\0") || id.startsWith(".") || isAbsolute(id)) return false;
+	return true;
+}
+/**
+* Loads (or reloads) the configured runner into the manager.
+*/
+async function loadRunnerInto(ctx, manager) {
+	const runner = await loadRunner(ctx.pluginConfig.runner || process.env.VERCUBE_DEV_RUNNER || "node-worker", {
+		name: VERCUBE_ENV,
+		data: { entry: devWorker }
+	});
+	await manager.reload(runner);
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* The Vercube Vite plugin.
+*
+* Runs a Vercube server inside a dedicated Vite environment via the Environment
+* API: controllers and services are auto-discovered from the project source,
+* assembled into a generated virtual entry, and executed in an isolated
+* env-runner worker with HMR. HTTP requests hitting the Vite dev server are
+* forwarded into that worker.
+*
+* @param pluginConfig - Optional plugin configuration.
+* @returns The array of Vite plugins composing the integration.
+*/
+function vercube(pluginConfig = {}) {
+	return [vercubeMain(createContext(pluginConfig))];
+}
+/**
+* The primary sub-plugin: defines the Vercube environment, warms the dev worker,
+* and forwards requests to it.
+*/
+function vercubeMain(ctx) {
+	let initialized = false;
+	return {
+		name: "vercube:main",
+		sharedDuringBuild: true,
+		async config(userConfig, configEnv) {
+			if (!initialized) {
+				initialized = true;
+				ctx.pluginConfig = defu(userConfig.vercube, ctx.pluginConfig);
+				await setupContext(ctx, {
+					root: userConfig.root ?? process.cwd(),
+					dev: configEnv.command === "serve"
+				});
+				if (ctx.dev) await initEnvRunner(ctx);
+			}
+			return {
+				builder: { sharedConfigBuild: true },
+				environments: {
+					client: { build: { outDir: resolve(ctx.root, CLIENT_OUT_DIR) } },
+					[VERCUBE_ENV]: createVercubeEnvironment(ctx)
+				}
+			};
+		},
+		buildApp: {
+			order: "post",
+			async handler(builder) {
+				const { buildEnvironments } = await import("./prod-Pc0_j1Kz.mjs");
+				await buildEnvironments(ctx, builder);
+			}
+		},
+		configureServer: async (server) => {
+			const { configureViteDevServer } = await import("./dev-Bl0akm-q.mjs");
+			return configureViteDevServer(ctx, server);
+		},
+		hotUpdate() {
+			if (this.environment.name !== "vercube") return;
+			this.environment.moduleGraph.invalidateAll();
+			this.environment.hot.send({ type: "full-reload" });
+		}
+	};
+}
+//#endregion
+export { VERCUBE_ENV, vercube };

package/dist/prod-Pc0_j1Kz.mjs

@@ -0,0 +1,28 @@
+import { t as VERCUBE_ENV } from "./types-Cpd32Lkt.mjs";
+import { resolve } from "pathe";
+import { existsSync } from "node:fs";
+//#region src/prod.ts
+/**
+* Production build orchestration for the `buildApp` hook.
+*
+* Builds every other configured environment first (for example a frontend
+* client added by another Vite plugin), then the Vercube server environment:
+* its generated entry is bundled to `dist/index.mjs`, exporting `fetch` and
+* starting a listener when run directly (`node dist/index.mjs`).
+*
+* @param ctx - The shared plugin context.
+* @param builder - Vite's builder, providing access to the configured environments.
+*/
+async function buildEnvironments(ctx, builder) {
+	const server = builder.environments[VERCUBE_ENV];
+	if (!server) throw new Error(`[vercube] Environment "${VERCUBE_ENV}" is not configured.`);
+	for (const [name, env] of Object.entries(builder.environments)) {
+		if (name === "vercube") continue;
+		const hasInput = !!env.config.build?.rollupOptions?.input;
+		const isClientWithHtml = env.config.consumer === "client" && existsSync(resolve(ctx.root, "index.html"));
+		if (hasInput || isClientWithHtml) await builder.build(env);
+	}
+	await builder.build(server);
+}
+//#endregion
+export { buildEnvironments };

package/dist/runtime/dev-worker.d.mts

@@ -0,0 +1,26 @@
+import { UpgradeContext } from "env-runner";
+
+//#region src/runtime/dev-worker.d.ts
+interface IpcContext {
+  sendMessage: (data: unknown) => void;
+}
+/**
+ * env-runner AppEntry: routes an incoming request to the named environment
+ * (defaulting to the Vercube server environment).
+ */
+declare function fetch(req: Request): Promise<Response>;
+/**
+ * env-runner AppEntry: forwards a WebSocket upgrade to the Vercube environment.
+ */
+declare function upgrade(context: UpgradeContext): void;
+/**
+ * env-runner IPC hooks: opens the message channel, registers environments, and
+ * relays module-runner transport messages.
+ */
+declare const ipc: {
+  onOpen(ctx: IpcContext): void;
+  onMessage(message: any): void;
+  onClose(): void;
+};
+//#endregion
+export { fetch, ipc, upgrade };

package/dist/runtime/dev-worker.mjs

@@ -0,0 +1,130 @@
+import { createViteTransport } from "env-runner/vite";
+import { ESModulesEvaluator, ModuleRunner } from "vite/module-runner";
+//#region src/runtime/dev-worker.ts
+let sendMessage;
+const messageListeners = /* @__PURE__ */ new Set();
+const envs = Object.create(null);
+/**
+* Owns the module runner and loaded entry for a single Vite environment.
+*/
+var ViteEnvRunner = class {
+	name;
+	runner;
+	#entryPath;
+	#entry;
+	#entryError;
+	constructor({ name, entry }) {
+		this.name = name;
+		this.#entryPath = entry;
+		const onMessage = (listener) => void messageListeners.add(listener);
+		const transport = createViteTransport((data) => sendMessage?.(data), onMessage, name);
+		const debug = typeof process !== "undefined" && process.env?.VERCUBE_DEBUG ? console.debug : void 0;
+		this.runner = new ModuleRunner({ transport }, new ESModulesEvaluator(), debug);
+		this.reload();
+	}
+	/**
+	* (Re)imports the entry module, capturing any load-time error to surface on fetch.
+	*/
+	async reload() {
+		try {
+			this.#entry = await this.runner.import(this.#entryPath);
+			this.#entryError = void 0;
+		} catch (error) {
+			console.error(error);
+			this.#entryError = error;
+		}
+	}
+	/**
+	* Dispatches a request into the entry's `fetch` handler, waiting briefly for a
+	* still-loading entry.
+	*/
+	async fetch(req) {
+		for (let i = 0; i < 5 && !(this.#entry || this.#entryError); i++) await new Promise((r) => setTimeout(r, 100 * 2 ** i));
+		if (this.#entryError) return renderError(this.#entryError);
+		const handler = this.#entry?.fetch ?? this.#entry?.default?.fetch;
+		if (!handler) return renderError(/* @__PURE__ */ new Error(`No fetch handler exported from ${this.#entryPath}`));
+		try {
+			return await handler(req);
+		} catch (error) {
+			return renderError(error);
+		}
+	}
+	/**
+	* Hands a raw Node HTTP upgrade to the entry's `handleUpgrade`, if it exports
+	* one (installed by `@vercube/ws`). No-op otherwise.
+	*/
+	async upgrade(context) {
+		const node = context.node;
+		if (node && this.#entry?.handleUpgrade) await this.#entry.handleUpgrade(node.req, node.socket, node.head);
+	}
+};
+/**
+* Reloads every registered environment's entry module.
+*/
+async function reloadAll() {
+	await Promise.all(Object.values(envs).map((env) => env?.reload()));
+}
+if (typeof process !== "undefined" && typeof process.on === "function") {
+	process.on("unhandledRejection", (error) => console.error(error));
+	process.on("uncaughtException", (error) => console.error(error));
+}
+/**
+* env-runner AppEntry: routes an incoming request to the named environment
+* (defaulting to the Vercube server environment).
+*/
+function fetch(req) {
+	const name = req?.headers.get("x-vite-env") || "vercube";
+	const env = envs[name];
+	if (!env) return Promise.resolve(renderError(/* @__PURE__ */ new Error(`Unknown vite environment "${name}"`)));
+	return env.fetch(req);
+}
+/**
+* env-runner AppEntry: forwards a WebSocket upgrade to the Vercube environment.
+*/
+function upgrade(context) {
+	envs["vercube"]?.upgrade(context);
+}
+/**
+* env-runner IPC hooks: opens the message channel, registers environments, and
+* relays module-runner transport messages.
+*/
+const ipc = {
+	onOpen(ctx) {
+		sendMessage = ctx.sendMessage;
+	},
+	onMessage(message) {
+		if (message?.type === "custom" && message.event === "vercube:vite-env") {
+			const { name, entry } = message.data;
+			envs[name] ??= new ViteEnvRunner({
+				name,
+				entry
+			});
+			return;
+		}
+		if (message?.type === "full-reload") {
+			reloadAll();
+			return;
+		}
+		for (const listener of messageListeners) listener(message);
+	},
+	onClose() {}
+};
+/**
+* Renders an error as a JSON HTTP 500 response.
+*/
+function renderError(error) {
+	const err = error;
+	return new Response(JSON.stringify({
+		status: err?.status ?? 500,
+		message: err?.message ?? String(error),
+		stack: err?.stack?.split("\n").map((l) => l.trim())
+	}, null, 2), {
+		status: err?.status ?? 500,
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "no-store"
+		}
+	});
+}
+//#endregion
+export { fetch, ipc, upgrade };

package/dist/types-Cpd32Lkt.mjs

@@ -0,0 +1,7 @@
+//#region src/types.ts
+/**
+* The Vite environment name under which the Vercube server runs.
+*/
+const VERCUBE_ENV = "vercube";
+//#endregion
+export { VERCUBE_ENV as t };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vercube/vite",
+  "version": "1.1.0",
+  "description": "Vite plugin integrating Vercube with the Vite Environment API",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercube/vercube.git",
+    "directory": "packages/vite"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./runtime/dev-worker": "./dist/runtime/dev-worker.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "vercube",
+    "vite",
+    "vite-plugin",
+    "environment-api",
+    "framework"
+  ],
+  "dependencies": {
+    "chokidar": "5.0.0",
+    "defu": "6.1.7",
+    "env-runner": "0.1.9",
+    "pathe": "2.0.3",
+    "rou3": "0.8.1",
+    "srvx": "0.11.17",
+    "@vercube/scan": "1.1.0"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "devDependencies": {
+    "vite": "8.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config ./tsdown.config.ts --config-loader=unrun"
+  }
+}