@vercube/nitro 1.0.0-beta.1

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,115 @@
+# @vercube/nitro
+
+Nitro integration for the [Vercube](https://github.com/vercube/vercube) framework. This package wires up Vercube's decorator-based controllers, services and middleware into a [Nitro](https://nitro.unjs.io/) server module, so you can use the full Vercube DI/decorator system without any extra glue code.
+
+## Installation
+
+```bash
+pnpm add @vercube/nitro
+```
+
+## Usage
+
+Add the plugin to your `nitro.config.ts`:
+
+```ts
+import { vercubeNitro } from '@vercube/nitro';
+
+export default defineNitroConfig({
+  modules: [
+    vercubeNitro({
+      // optional path to a boot file that runs before the app starts
+      setupFile: './src/boot/boot.ts',
+    }),
+  ],
+});
+```
+
+### Boot file
+
+The `setupFile` is a regular TypeScript module that exports a default function. It receives the Vercube `App` instance and is the right place to configure your DI container, register providers, or run any startup logic.
+
+```ts
+// src/boot/boot.ts
+import type { App } from '@vercube/core';
+
+export default async function boot(app: App) {
+  // configure the app here
+}
+```
+
+### Controllers
+
+Annotate your classes with `@Controller` and HTTP method decorators. The plugin discovers them automatically at build time.
+
+```ts
+import { Controller, Get, Post } from '@vercube/core';
+
+@Controller('/users')
+export class UserController {
+  @Get('/')
+  list() {
+    return [{ id: 1, name: 'Alice' }];
+  }
+
+  @Post('/')
+  create() {
+    return { id: 2, name: 'Bob' };
+  }
+}
+```
+
+Place your controllers in the `api/` or `routes/` directory (configurable via `nitro.config.ts` options `apiDir` / `routesDir`).
+
+### Services
+
+Services decorated with `@Injectable` are discovered and registered in the DI container automatically. Place them anywhere inside the directories listed in `scanDirs`.
+
+```ts
+import { Injectable } from '@vercube/di';
+
+@Injectable()
+export class UserService {
+  findAll() {
+    return [];
+  }
+}
+```
+
+### Middleware
+
+Classes that extend `BaseMiddleware` are picked up and registered automatically.
+
+```ts
+import { BaseMiddleware } from '@vercube/core';
+
+export class AuthMiddleware extends BaseMiddleware {
+  async onRequest(event: any) {
+    // validate token, etc.
+  }
+}
+```
+
+### Storage
+
+`@vercube/nitro` ships a `NitroStorageManager` that wraps Nitro's built-in storage layer. Configure your storage drivers in `nitro.config.ts` under `storage`, then inject `StorageManager` in your services as usual.
+
+```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  storage: {
+    cache: { driver: 'memory' },
+  },
+});
+```
+
+## Options
+
+| Option      | Type       | Default | Description                                           |
+| ----------- | ---------- | ------- | ----------------------------------------------------- |
+| `setupFile` | `string`   | -       | Path to the boot file executed before the app starts  |
+| `scanDirs`  | `string[]` | `[]`    | Extra directories to scan for services and middleware |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import { createNitroApp } from "./runtime/App.mjs";
+import { App } from "@vercube/core";
+import { NitroModule } from "nitro/types";
+
+//#region src/plugin/VercubePlugin.d.ts
+interface PluginOptions {
+  scanDirs?: string[];
+  /**
+   * Path to a file that exports a default function for customizing the Vercube app
+   * before the DI container is flushed. Use this to bind tokens, override services,
+   * or perform any setup that auto-discovery cannot handle.
+   *
+   * The file must export a default function matching: `(app: App) => void | Promise<void>`
+   *
+   * @example
+   * // nitro.config.ts
+   * vercubeNitro({ setupFile: './src/container.ts' })
+   *
+   * // src/container.ts
+   * import type { App } from '@vercube/core'
+   * export default async (app: App) => {
+   *   app.container.bind(DatabaseToken, PostgresDatabase)
+   * }
+   */
+  setupFile?: string;
+}
+declare function vercubeNitro(options?: PluginOptions): NitroModule;
+//#endregion
+//#region src/helpers/helpers.d.ts
+declare function useVercubeApp(): App | undefined;
+//#endregion
+export { createNitroApp, useVercubeApp, vercubeNitro };

package/dist/index.mjs

@@ -0,0 +1,594 @@
+import { createNitroApp } from "./runtime/App.mjs";
+import { destroyContainer } from "@vercube/di";
+import { defu } from "defu";
+import { join, relative, resolve } from "pathe";
+import { watch } from "chokidar";
+import { readFileSync } from "node:fs";
+import { glob } from "tinyglobby";
+import { parseSync } from "oxc-parser";
+//#region src/helpers/helpers.ts
+function useVercubeApp() {
+	return globalThis.__vercubeApp__;
+}
+//#endregion
+//#region src/validators/BundlerValidator.ts
+/**
+* Validates the bundler options for the nitro instance
+* @param nitro - The nitro instance
+* @returns void
+*/
+function validateBundler(nitro) {
+	if (nitro.options.builder !== "rolldown") throw new Error("Vercube Nitro module requires the rolldown builder");
+}
+//#endregion
+//#region src/validators/TypescriptValidator.ts
+/**
+* Validates the typescript options for experimentalDecorators
+* @param nitro - The nitro instance
+* @returns void
+*/
+function validateTypescript(nitro) {
+	const tsConfig = nitro.options.typescript;
+	if (typeof tsConfig?.tsConfig === "string") {
+		if (!JSON.parse(readFileSync(tsConfig.tsConfig, "utf8")).compilerOptions?.experimentalDecorators) throw new Error(`Vercube requires "experimentalDecorators" to be enabled in your tsconfig (${tsConfig.tsConfig}). Please add "experimentalDecorators": true to your compilerOptions.`);
+	} else if (typeof tsConfig?.tsConfig === "object" && tsConfig.tsConfig !== null) tsConfig.tsConfig.compilerOptions = {
+		...tsConfig.tsConfig.compilerOptions,
+		experimentalDecorators: true
+	};
+}
+//#endregion
+//#region src/_internal/scan.ts
+const GLOB_SCAN_PATTERN = "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+async function scanFiles(nitro, name) {
+	return await Promise.all(nitro.options.scanDirs.map((dir) => scanDir(nitro, dir, name))).then((r) => r.flat());
+}
+async function scanDir(nitro, dir, name) {
+	return (await glob(join(name, GLOB_SCAN_PATTERN), {
+		cwd: dir,
+		dot: true,
+		absolute: true
+	}).catch((error) => {
+		if (error?.code === "ENOTDIR") {
+			nitro.logger.warn(`Ignoring \`${join(dir, name)}\`. It must be a directory.`);
+			return [];
+		}
+		throw error;
+	})).map((fullPath) => {
+		return {
+			fullPath,
+			path: relative(join(dir, name), fullPath)
+		};
+	}).sort((a, b) => a.path.localeCompare(b.path));
+}
+//#endregion
+//#region src/build/Routes.ts
+/**
+* Mapping of decorator names to their corresponding uppercase HTTP method strings.
+* Used for O(1) lookup and simultaneous method name resolution.
+*/
+const HTTP_METHODS = {
+	Get: "GET",
+	Post: "POST",
+	Put: "PUT",
+	Delete: "DELETE",
+	Patch: "PATCH",
+	Options: "OPTIONS",
+	Head: "HEAD"
+};
+/**
+* Pre-compiled regular expression for extracting named route parameters.
+* Matches path segments prefixed with ':' (e.g. ':id', ':slug').
+* Uses the global flag for iterative matching via `exec`.
+*/
+const PARAM_RE = /:([^/]+)/g;
+/**
+* Internal module path used for generated import statements.
+*/
+const IMPORT_SOURCE = "#internal/vercube-route-plugin";
+/**
+* Reads a controller file from disk and returns all routes defined in classes
+* decorated with `Controller` and methods decorated with HTTP decorators (Get, Post, etc.).
+* @param route - File info (path and fullPath) to analyze.
+* @returns List of `RouteInfo` for every route in the file.
+*/
+async function transformRoute(route) {
+	return extractRoutes(readFileSync(route.fullPath, "utf8")).map((parsedRoute) => ({
+		...parsedRoute,
+		...route
+	}));
+}
+/**
+* Extracts all route definitions from the given TypeScript/JavaScript source code.
+*
+* Parses the source using `oxc-parser` and traverses the resulting AST to find
+* classes decorated with `@Controller(path)`. For each such class, it inspects
+* method definitions for HTTP method decorators (`@Get`, `@Post`, `@Put`, `@Delete`,
+* `@Patch`, `@Options`, `@Head`) and constructs full route paths by concatenating
+* the controller base path with the method-level path.
+*
+* Generates appropriate import statements based on the export style:
+* - `export default class Foo` → `import Foo from '...'`
+* - `export class Foo` → `import { Foo } from '...'`
+*
+* Supports classes declared via `export class`, `export default class`,
+* and plain `class` declarations.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link RouteInfo} objects representing all discovered routes.
+*/
+function extractRoutes(code) {
+	const ast = parseSync("file.ts", code).program;
+	const routes = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode$2(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		const basePath = extractDecoratorArg(classNode.decorators, "Controller");
+		if (basePath === null) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		const importStatement = isDefault ? `import ${className} from '${IMPORT_SOURCE}';` : `import { ${className} } from '${IMPORT_SOURCE}';`;
+		for (const member of classNode.body?.body ?? []) {
+			if (member.type !== "MethodDefinition") continue;
+			for (const decorator of member.decorators ?? []) {
+				const expr = decorator.expression;
+				if (expr?.type !== "CallExpression") continue;
+				const method = HTTP_METHODS[expr.callee?.name];
+				if (!method) continue;
+				const arg = expr.arguments?.[0];
+				const fullRoute = normalizePath(basePath + (arg?.type === "Literal" && typeof arg.value === "string" ? arg.value : ""));
+				routes.push({
+					import: importStatement,
+					importClassName: className,
+					route: fullRoute,
+					method,
+					fullPath: "",
+					path: "",
+					params: extractParams(fullRoute)
+				});
+			}
+		}
+	}
+	return routes;
+}
+/**
+* Unwraps export declarations to retrieve the underlying class node,
+* along with metadata about the export style.
+*
+* Handles the following AST patterns:
+* - `ExportDefaultDeclaration` wrapping a `ClassDeclaration` → `isDefault: true`
+* - `ExportNamedDeclaration` wrapping a `ClassDeclaration` → `isDefault: false`
+* - Direct `ClassDeclaration` or `Class` nodes → `isDefault: false`
+*
+* @param node - An AST node from the program body to inspect.
+* @returns An object containing the class AST node and whether it is a default export, or `null` if not a class.
+*/
+function getClassNode$2(node) {
+	if (node.type === "ExportDefaultDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: true
+		};
+	}
+	if (node.type === "ExportNamedDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: false
+		};
+	}
+	if (node?.type === "ClassDeclaration" || node?.type === "Class") return {
+		classNode: node,
+		isDefault: false
+	};
+	return null;
+}
+/**
+* Searches a list of decorators for a `CallExpression` matching the given name
+* and extracts its first string argument.
+*
+* This is used to retrieve the path argument from decorators like `@Controller('/api/foo')`.
+* If the decorator is found but has no string argument, an empty string is returned.
+* If no matching decorator is found, `null` is returned.
+*
+* @param decorators - The array of decorator AST nodes to search, or `undefined` if none exist.
+* @param name - The decorator function name to match against (e.g. 'Controller').
+* @returns The string argument value, an empty string if no argument is provided, or `null` if the decorator is not found.
+*/
+function extractDecoratorArg(decorators, name) {
+	if (!decorators) return null;
+	for (const dec of decorators) {
+		const expr = dec.expression;
+		if (expr?.type === "CallExpression" && expr.callee?.name === name) {
+			const arg = expr.arguments?.[0];
+			if (arg?.type === "Literal" && typeof arg.value === "string") return arg.value;
+			return "";
+		}
+	}
+	return null;
+}
+/**
+* Normalizes a route path by removing duplicate slashes and ensuring
+* the path starts with a single leading slash.
+*
+* Splits the path on '/' separators, filters out empty segments,
+* and rejoins with single '/' separators.
+*
+* @param path - The raw concatenated path string to normalize.
+* @returns A cleaned path string with a leading slash and no duplicate separators.
+*/
+function normalizePath(path) {
+	return "/" + path.split("/").filter(Boolean).join("/");
+}
+/**
+* Extracts named route parameters from a path string.
+*
+* Scans the path for segments prefixed with ':' using a pre-compiled
+* regular expression and returns an array of parameter names with
+* the ':' prefix stripped.
+*
+* Resets the regex `lastIndex` after each invocation to ensure
+* consistent behavior across repeated calls.
+*
+* @param route - The normalized route path to scan for parameters.
+* @returns An array of parameter name strings, empty if none are found.
+*/
+function extractParams(route) {
+	const params = [];
+	let match;
+	while (match = PARAM_RE.exec(route)) params.push(match[1]);
+	PARAM_RE.lastIndex = 0;
+	return params;
+}
+//#endregion
+//#region src/setup/Routes.ts
+async function setupRoutes(nitro) {
+	/**
+	* Scan files in the api and routes directories
+	* @param nitro - The nitro instance
+	* @returns void
+	*/
+	const routes = await getTransformedRoutes(nitro);
+	nitro.options.handlers = clearRoutes(nitro.options.handlers);
+	nitro.options.handlers.push(...routes.map((route) => ({
+		route: route.route,
+		method: route.method,
+		handler: `@vercube/nitro/runtime/handler`,
+		lazy: true
+	})));
+	nitro.options.ignore = [...new Set([...nitro.options.ignore ?? [], ...routes.map((route) => route.fullPath.replace(nitro.options.rootDir, "").replace(String(nitro.options?.serverDir), "").replace("src/", ""))])];
+	nitro.routing.sync();
+}
+/**
+* Gets the transformed routes from the routes directory
+* @param nitro - The nitro instance
+* @returns The transformed routes
+*/
+async function getTransformedRoutes(nitro) {
+	const routes = await scanRoutes(nitro);
+	return (await Promise.all(routes.map(async (route) => await transformRoute(route))).then((r) => r.flat())).map((route) => ({
+		...route,
+		import: route.import.replace(IMPORT_SOURCE, route.fullPath)
+	}));
+}
+/**
+* Scans the routes directory and returns the file info of the routes
+* @param nitro - The nitro instance
+* @returns The file info of the routes
+*/
+async function scanRoutes(nitro) {
+	return Promise.all([scanFiles(nitro, nitro.options.apiDir || "api"), scanFiles(nitro, nitro.options.routesDir || "routes")]).then((r) => r.flat());
+}
+/**
+* Clears the routes from the handlers
+* @param handlers - The handlers
+* @returns void
+*/
+function clearRoutes(handlers) {
+	return handlers.filter((handler) => handler.handler !== "@vercube/nitro/runtime/handler");
+}
+//#endregion
+//#region src/setup/Hooks.ts
+function setupHooks(nitro, options) {
+	/**
+	* Validates the bundler and typescript options for the nitro instance
+	* @param nitro - The nitro instance
+	* @returns void
+	*/
+	nitro.hooks.hook("build:before", async () => {
+		validateBundler(nitro);
+		validateTypescript(nitro);
+		await setupRoutes(nitro);
+	});
+	nitro.hooks.hook("compiled", async () => {
+		await setupRoutes(nitro);
+		nitro.routing.sync();
+	});
+	/**
+	* In dev mode, watch controller files for content changes.
+	* Nitro's built-in watcher only reacts to add/unlink events (not `change`),
+	* and Rollup only watches files it directly imports. Controller files
+	* decorated with @Controller are not imported by Rollup, so their changes
+	* are invisible to Nitro. This watcher bridges that gap.
+	*/
+	if (nitro.options.dev) {
+		const watcher = watch(nitro.options.scanDirs.flatMap((dir) => [
+			join(dir, nitro.options.apiDir || "api"),
+			join(dir, nitro.options.routesDir || "routes"),
+			join(dir, "middleware"),
+			...options?.scanDirs ?? []
+		]), { ignoreInitial: true }).on("change", async () => {
+			await nitro.hooks.callHook("compiled", nitro);
+		});
+		nitro.hooks.hook("close", () => watcher.close());
+	}
+	/**
+	* Destroys the Vercube container
+	* @param nitro - The nitro instance
+	* @returns void
+	*/
+	nitro.hooks.hook("close", async () => {
+		const app = useVercubeApp();
+		if (!app) return;
+		destroyContainer(app.container);
+	});
+}
+//#endregion
+//#region src/build/Middleware.ts
+/**
+* Internal module path used as a placeholder in generated import statements.
+* Replaced with the actual file path during setup.
+*/
+const MIDDLEWARE_IMPORT_SOURCE = "#internal/vercube-middleware-source";
+/**
+* Reads a file from disk and returns all classes extending `BaseMiddleware` found within it.
+*/
+async function transformMiddleware(file) {
+	return extractMiddlewares(readFileSync(file.fullPath, "utf8")).map((m) => ({
+		...m,
+		...file
+	}));
+}
+/**
+* Extracts all class definitions that extend `BaseMiddleware` from the given source code.
+*
+* Parses the source using `oxc-parser` and traverses the AST to find classes
+* whose `superClass` resolves to the identifier `BaseMiddleware`. Generates
+* appropriate import statements based on whether the class is a default or named export.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link MiddlewareInfo} objects for all discovered middleware classes.
+*/
+function extractMiddlewares(code) {
+	const ast = parseSync("file.ts", code).program;
+	const middlewares = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode$1(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		if (!extendsBaseMiddleware(classNode)) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		const importStatement = isDefault ? `import ${className} from '${MIDDLEWARE_IMPORT_SOURCE}';` : `import { ${className} } from '${MIDDLEWARE_IMPORT_SOURCE}';`;
+		middlewares.push({
+			import: importStatement,
+			importClassName: className,
+			fullPath: "",
+			path: ""
+		});
+	}
+	return middlewares;
+}
+/**
+* Returns true if the class node extends `BaseMiddleware`.
+*/
+function extendsBaseMiddleware(classNode) {
+	return classNode.superClass?.type === "Identifier" && classNode.superClass.name === "BaseMiddleware";
+}
+/**
+* Unwraps export declarations to retrieve the underlying class node,
+* along with metadata about the export style.
+*/
+function getClassNode$1(node) {
+	if (node.type === "ExportDefaultDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: true
+		};
+	}
+	if (node.type === "ExportNamedDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: false
+		};
+	}
+	if (node?.type === "ClassDeclaration" || node?.type === "Class") return {
+		classNode: node,
+		isDefault: false
+	};
+	return null;
+}
+//#endregion
+//#region src/setup/Middleware.ts
+/**
+* Gets the transformed middleware from the middleware directory.
+*/
+async function getTransformedMiddlewares(nitro) {
+	const files = await scanMiddlewares(nitro);
+	return (await Promise.all(files.map((file) => transformMiddleware(file))).then((r) => r.flat())).map((middleware) => ({
+		...middleware,
+		import: middleware.import.replace(MIDDLEWARE_IMPORT_SOURCE, middleware.fullPath)
+	}));
+}
+/**
+* Scans the middleware directory for classes extending `BaseMiddleware` and
+* excludes those files from Nitro's native middleware handling.
+*/
+async function scanMiddlewares(nitro) {
+	const files = await scanFiles(nitro, "middleware");
+	nitro.options.ignore = [...new Set([...nitro.options.ignore ?? [], ...files.map((file) => file.fullPath.replace(nitro.options.rootDir, "").replace(String(nitro.options?.serverDir), "").replace("src/", ""))])];
+	return files;
+}
+//#endregion
+//#region src/build/Services.ts
+/**
+* Internal module path used as a placeholder in generated import statements.
+* Replaced with the actual file path during setup.
+*/
+const SERVICE_IMPORT_SOURCE = "#internal/vercube-service-source";
+/**
+* Reads a file from disk and returns all `@Injectable`-decorated classes found within it.
+*/
+async function transformService(file) {
+	return extractServices(readFileSync(file.fullPath, "utf8")).map((s) => ({
+		...s,
+		...file
+	}));
+}
+/**
+* Extracts all `@Injectable`-decorated class definitions from the given source code.
+*
+* Parses the source using `oxc-parser` and traverses the AST to find classes
+* annotated with `@Injectable()`. Generates appropriate import statements based
+* on whether the class is a default or named export.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link ServiceInfo} objects for all discovered injectable classes.
+*/
+function extractServices(code) {
+	const ast = parseSync("file.ts", code).program;
+	const services = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		if (!hasDecorator(classNode.decorators, "Injectable")) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		const importStatement = isDefault ? `import ${className} from '${SERVICE_IMPORT_SOURCE}';` : `import { ${className} } from '${SERVICE_IMPORT_SOURCE}';`;
+		services.push({
+			import: importStatement,
+			importClassName: className,
+			fullPath: "",
+			path: ""
+		});
+	}
+	return services;
+}
+/**
+* Unwraps export declarations to retrieve the underlying class node,
+* along with metadata about the export style.
+*/
+function getClassNode(node) {
+	if (node.type === "ExportDefaultDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: true
+		};
+	}
+	if (node.type === "ExportNamedDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: false
+		};
+	}
+	if (node?.type === "ClassDeclaration" || node?.type === "Class") return {
+		classNode: node,
+		isDefault: false
+	};
+	return null;
+}
+/**
+* Returns true if the given decorators array contains a decorator matching `name`.
+* Supports both `@Name` identifier and `@Name()` call expression styles.
+*/
+function hasDecorator(decorators, name) {
+	if (!decorators) return false;
+	for (const dec of decorators) {
+		const expr = dec.expression;
+		if (expr?.type === "CallExpression" && expr.callee?.name === name) return true;
+		if (expr?.type === "Identifier" && expr.name === name) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/setup/Services.ts
+/**
+* Scans the project source directory for `@Injectable`-decorated classes and returns
+* their transformed service info with resolved import paths.
+*/
+async function getTransformedServices(nitro, scanDirs) {
+	const files = await scanServices(nitro, scanDirs);
+	return (await Promise.all(files.map((file) => transformService(file))).then((r) => r.flat())).map((service) => ({
+		...service,
+		import: service.import.replace(SERVICE_IMPORT_SOURCE, service.fullPath)
+	}));
+}
+/**
+* Scans the root of each scanDir for `@Injectable`-decorated service files.
+* scanDirs already points to the server source root (e.g. `src/`), so we scan
+* from `.` to cover all subdirectories without adding an extra path segment.
+*/
+async function scanServices(nitro, scanDirs) {
+	return Promise.all(scanDirs?.map((dir) => scanFiles(nitro, dir)) ?? [scanFiles(nitro, ".")]).then((r) => r.flat());
+}
+//#endregion
+//#region src/plugin/VercubePlugin.ts
+const defaultOptions = { scanDirs: [
+	"api",
+	"routes",
+	"services",
+	"repositories"
+] };
+function vercubeNitro(options) {
+	options = defu(options, defaultOptions);
+	return {
+		name: "@vercube/nitro",
+		setup: async (nitro) => {
+			setupHooks(nitro, options);
+			const routeMap = /* @__PURE__ */ new Map();
+			for (const route of await getTransformedRoutes(nitro)) routeMap.set(route.path, route);
+			const routes = [...routeMap.values()];
+			const serviceMap = /* @__PURE__ */ new Map();
+			for (const service of await getTransformedServices(nitro, options?.scanDirs)) serviceMap.set(`${service.fullPath}:${service.importClassName}`, service);
+			const services = [...serviceMap.values()];
+			await getTransformedMiddlewares(nitro);
+			const routeClassNames = new Set(routes.map((r) => r.importClassName));
+			const uniqueServices = services.filter((s) => !routeClassNames.has(s.importClassName));
+			const setupFilePath = options?.setupFile ? resolve(nitro.options.rootDir, options.setupFile) : null;
+			nitro.options.virtual["#internal/vercube-route-plugin"] = `
+        import { definePlugin } from 'nitro';
+        import { createNitroApp } from '@vercube/nitro';
+        ${setupFilePath ? `import __vercubeSetup__ from '${setupFilePath}';` : ""}
+
+        ${routes.map((route) => route.import).join("\n")}
+        ${uniqueServices.map((service) => service.import).join("\n")}
+
+        export default definePlugin(async (nitroApp) => {
+          const app = await createNitroApp(${JSON.stringify(nitro.options)});
+          nitroApp.__vercubeApp__ = app;
+          globalThis.__vercubeApp__ = app;
+
+          // bind routes to container
+          ${routes.map((route) => `app.container.bind(${route.importClassName});`).join("\n")}
+
+          // bind services to container
+          ${uniqueServices.map((service) => `app.container.bind(${service.importClassName});`).join("\n")}
+
+          ${setupFilePath ? `await __vercubeSetup__(app);` : ""}
+
+          app.container.flushQueue();
+
+        });
+      `;
+			nitro.options.plugins.push("#internal/vercube-route-plugin");
+		}
+	};
+}
+//#endregion
+export { createNitroApp, useVercubeApp, vercubeNitro };

package/dist/runtime/App.d.mts

@@ -0,0 +1,12 @@
+import { App } from "@vercube/core";
+import { NitroOptions } from "nitro/types";
+
+//#region src/runtime/App.d.ts
+/**
+ * Create a Vercube application from a Nitro instance.
+ * @param nitro - The Nitro instance.
+ * @returns The Vercube application.
+ */
+declare function createNitroApp(nitroOpts: NitroOptions): Promise<App>;
+//#endregion
+export { createNitroApp };

package/dist/runtime/App.mjs

@@ -0,0 +1,38 @@
+import { NitroStorageManager } from "./Storage.mjs";
+import { createApp } from "@vercube/core";
+import { initializeContainer } from "@vercube/di";
+import { StorageManager } from "@vercube/storage";
+//#region src/runtime/App.ts
+/**
+* Create a Vercube application from a Nitro instance.
+* @param nitro - The Nitro instance.
+* @returns The Vercube application.
+*/
+async function createNitroApp(nitroOpts) {
+	const app = await createApp({ cfg: {
+		logLevel: getLogLevel(nitroOpts.logLevel),
+		production: !nitroOpts.dev,
+		dev: nitroOpts.dev,
+		runtime: { ...nitroOpts.runtimeConfig }
+	} });
+	app.container.bind(StorageManager, NitroStorageManager);
+	initializeContainer(app.container);
+	return app;
+}
+/**
+* Get the Vercube log level from a Nitro log level.
+* @param logLevel - The Nitro log level.
+* @returns The Vercube log level.
+*/
+function getLogLevel(logLevel) {
+	switch (logLevel) {
+		case 0: return "debug";
+		case 1: return "error";
+		case 2: return "warn";
+		case 3: return "info";
+		default:
+		case 4: return "debug";
+	}
+}
+//#endregion
+export { createNitroApp };

package/dist/runtime/RouteHandler.d.mts

@@ -0,0 +1,4 @@
+//#region src/runtime/RouteHandler.d.ts
+declare const _default: import("nitro/h3").EventHandlerWithFetch<import("nitro/h3").EventHandlerRequest, unknown>;
+//#endregion
+export { _default as default };

package/dist/runtime/RouteHandler.mjs

@@ -0,0 +1,9 @@
+import { defineEventHandler } from "nitro/h3";
+//#region src/runtime/RouteHandler.ts
+var RouteHandler_default = defineEventHandler({ fetch: async (event) => {
+	const app = globalThis.__vercubeApp__;
+	if (!app) throw new Error("Vercube app is not initialized");
+	return app.fetch(event);
+} });
+//#endregion
+export { RouteHandler_default as default };

package/dist/runtime/Storage.d.mts

@@ -0,0 +1,119 @@
+import { Storage, StorageManager, StorageTypes } from "@vercube/storage";
+
+//#region src/runtime/Storage.d.ts
+/**
+ * Manages multiple storage instances and provides a unified interface for storage operations.
+ * Each storage instance is identified by a unique name and implements the Storage interface.
+ * This class handles initialization, registration, and delegation of storage operations.
+ */
+declare class NitroStorageManager extends StorageManager {
+  /**
+   * Mounts a new storage instance with the specified name
+   * @param {StorageTypes.Mount} params - Mount parameters containing name and storage implementation
+   * @param {string} [params.name] - Optional name for the storage instance, defaults to 'default'
+   * @param {IOC.Newable<Storage>} params.storage - Storage implementation to mount
+   * @returns {Promise<void>} A promise that resolves when mounting is complete
+   */
+  mount<T extends Storage<unknown>>(_opts: StorageTypes.Mount<T>): Promise<void>;
+  /**
+   * Retrieves a registered storage instance by name
+   * @param {string} name - Name of the storage instance to retrieve
+   * @returns {Storage | undefined} The storage instance if found, undefined otherwise
+   */
+  getStorage(name?: string): Storage | undefined;
+  /**
+   * Retrieves an item from the specified storage
+   * @template T - Type of the stored value
+   * @param {StorageTypes.GetItem} params - Parameters for retrieving an item
+   * @param {string} [params.storage] - Name of the storage to retrieve from, defaults to 'default'
+   * @param {string} params.key - Key of the item to retrieve
+   * @returns {Promise<T | null>} A promise that resolves with the stored value or null if not found
+   */
+  getItem<T = unknown>({
+    storage,
+    key
+  }: StorageTypes.GetItem): Promise<T | null>;
+  /**
+   * Retrieves multiple items from the specified storage
+   * @template T - Type of the stored value
+   * @param {StorageTypes.GetItems} params - Parameters for retrieving multiple items
+   * @param {string} [params.storage] - Name of the storage to retrieve from, defaults to 'default'
+   * @param {string[]} params.keys - Keys of the items to retrieve
+   * @returns {Promise<T[]>} A promise that resolves with the stored values or empty array if not found
+   */
+  getItems<T = unknown>({
+    storage,
+    keys
+  }: StorageTypes.GetItems): Promise<T[]>;
+  /**
+   * Stores an item in the specified storage
+   * @template T - Type of the value to store
+   * @param {StorageTypes.SetItem<T>} params - Parameters for storing an item
+   * @param {string} [params.storage] - Name of the storage to store in, defaults to 'default'
+   * @param {string} params.key - Key under which to store the value
+   * @param {T} params.value - Value to store
+   * @returns {Promise<void>} A promise that resolves when the value is stored
+   */
+  setItem<T = unknown, U = unknown>({
+    storage,
+    key,
+    value,
+    options
+  }: StorageTypes.SetItem<T, U>): Promise<void>;
+  /**
+   * Deletes an item from the specified storage
+   * @param {StorageTypes.DeleteItem} params - Parameters for deleting an item
+   * @param {string} [params.storage] - Name of the storage to delete from, defaults to 'default'
+   * @param {string} params.key - Key of the item to delete
+   * @returns {Promise<void>} A promise that resolves when the item is deleted
+   */
+  deleteItem({
+    storage,
+    key
+  }: StorageTypes.DeleteItem): Promise<void>;
+  /**
+   * Checks if an item exists in the specified storage
+   * @param {StorageTypes.HasItem} params - Parameters for checking item existence
+   * @param {string} [params.storage] - Name of the storage to check, defaults to 'default'
+   * @param {string} params.key - Key to check for
+   * @returns {Promise<boolean>} A promise that resolves to true if the item exists, false otherwise
+   */
+  hasItem({
+    storage,
+    key
+  }: StorageTypes.HasItem): Promise<boolean>;
+  /**
+   * Retrieves all keys from the specified storage
+   * @param {StorageTypes.GetKeys} params - Parameters for retrieving keys
+   * @param {string} [params.storage] - Name of the storage to get keys from, defaults to 'default'
+   * @returns {Promise<string[]>} A promise that resolves with an array of all keys
+   */
+  getKeys({
+    storage
+  }: StorageTypes.GetKeys): Promise<string[]>;
+  /**
+   * Clears all items from the specified storage
+   * @param {StorageTypes.Clear} params - Parameters for clearing storage
+   * @param {string} [params.storage] - Name of the storage to clear, defaults to 'default'
+   * @returns {Promise<void>} A promise that resolves when the storage is cleared
+   */
+  clear({
+    storage
+  }: StorageTypes.Clear): Promise<void>;
+  /**
+   * Gets the number of items in the specified storage
+   * @param {StorageTypes.Size} params - Parameters for getting storage size
+   * @param {string} [params.storage] - Name of the storage to get size of, defaults to 'default'
+   * @returns {Promise<number>} A promise that resolves with the number of items
+   */
+  size({
+    storage
+  }: StorageTypes.Size): Promise<number>;
+  /**
+   * Initializes the storage manager
+   * @returns {Promise<void>} A promise that resolves when the storage manager is initialized
+   */
+  protected init(): Promise<void>;
+}
+//#endregion
+export { NitroStorageManager };

package/dist/runtime/Storage.mjs

@@ -0,0 +1,129 @@
+import { StorageManager } from "@vercube/storage";
+import { useStorage } from "nitro/storage";
+//#region src/runtime/Storage.ts
+/**
+* Manages multiple storage instances and provides a unified interface for storage operations.
+* Each storage instance is identified by a unique name and implements the Storage interface.
+* This class handles initialization, registration, and delegation of storage operations.
+*/
+var NitroStorageManager = class extends StorageManager {
+	/**
+	* Mounts a new storage instance with the specified name
+	* @param {StorageTypes.Mount} params - Mount parameters containing name and storage implementation
+	* @param {string} [params.name] - Optional name for the storage instance, defaults to 'default'
+	* @param {IOC.Newable<Storage>} params.storage - Storage implementation to mount
+	* @returns {Promise<void>} A promise that resolves when mounting is complete
+	*/
+	async mount(_opts) {
+		this.gLogger?.warn("NitroStorageManager::mount", "mounting storage is not supported for Nitro. Use options.storage in nitro.config.ts instead");
+	}
+	/**
+	* Retrieves a registered storage instance by name
+	* @param {string} name - Name of the storage instance to retrieve
+	* @returns {Storage | undefined} The storage instance if found, undefined otherwise
+	*/
+	getStorage(name = "") {
+		const storage = useStorage(name) || useStorage();
+		return {
+			getItem: storage.getItem.bind(storage),
+			getItems: async (keys) => (await storage.getItems(keys)).map((item) => item.value),
+			setItem: storage.setItem.bind(storage),
+			hasItem: storage.hasItem.bind(storage),
+			getKeys: storage.getKeys.bind(storage),
+			clear: storage.clear.bind(storage),
+			deleteItem: storage.removeItem.bind(storage),
+			size: () => {
+				this.gLogger?.warn("NitroStorageManager::size", "getting size is not supported for Nitro Storage.");
+				return 0;
+			}
+		};
+	}
+	/**
+	* Retrieves an item from the specified storage
+	* @template T - Type of the stored value
+	* @param {StorageTypes.GetItem} params - Parameters for retrieving an item
+	* @param {string} [params.storage] - Name of the storage to retrieve from, defaults to 'default'
+	* @param {string} params.key - Key of the item to retrieve
+	* @returns {Promise<T | null>} A promise that resolves with the stored value or null if not found
+	*/
+	async getItem({ storage, key }) {
+		return this.getStorage(storage)?.getItem(key) ?? null;
+	}
+	/**
+	* Retrieves multiple items from the specified storage
+	* @template T - Type of the stored value
+	* @param {StorageTypes.GetItems} params - Parameters for retrieving multiple items
+	* @param {string} [params.storage] - Name of the storage to retrieve from, defaults to 'default'
+	* @param {string[]} params.keys - Keys of the items to retrieve
+	* @returns {Promise<T[]>} A promise that resolves with the stored values or empty array if not found
+	*/
+	async getItems({ storage, keys }) {
+		return this.getStorage(storage)?.getItems(keys) ?? [];
+	}
+	/**
+	* Stores an item in the specified storage
+	* @template T - Type of the value to store
+	* @param {StorageTypes.SetItem<T>} params - Parameters for storing an item
+	* @param {string} [params.storage] - Name of the storage to store in, defaults to 'default'
+	* @param {string} params.key - Key under which to store the value
+	* @param {T} params.value - Value to store
+	* @returns {Promise<void>} A promise that resolves when the value is stored
+	*/
+	async setItem({ storage, key, value, options }) {
+		this.getStorage(storage)?.setItem(key, value, options);
+	}
+	/**
+	* Deletes an item from the specified storage
+	* @param {StorageTypes.DeleteItem} params - Parameters for deleting an item
+	* @param {string} [params.storage] - Name of the storage to delete from, defaults to 'default'
+	* @param {string} params.key - Key of the item to delete
+	* @returns {Promise<void>} A promise that resolves when the item is deleted
+	*/
+	async deleteItem({ storage, key }) {
+		this.getStorage(storage)?.deleteItem(key);
+	}
+	/**
+	* Checks if an item exists in the specified storage
+	* @param {StorageTypes.HasItem} params - Parameters for checking item existence
+	* @param {string} [params.storage] - Name of the storage to check, defaults to 'default'
+	* @param {string} params.key - Key to check for
+	* @returns {Promise<boolean>} A promise that resolves to true if the item exists, false otherwise
+	*/
+	async hasItem({ storage, key }) {
+		return this.getStorage(storage)?.hasItem(key) ?? false;
+	}
+	/**
+	* Retrieves all keys from the specified storage
+	* @param {StorageTypes.GetKeys} params - Parameters for retrieving keys
+	* @param {string} [params.storage] - Name of the storage to get keys from, defaults to 'default'
+	* @returns {Promise<string[]>} A promise that resolves with an array of all keys
+	*/
+	async getKeys({ storage }) {
+		return this.getStorage(storage)?.getKeys() ?? [];
+	}
+	/**
+	* Clears all items from the specified storage
+	* @param {StorageTypes.Clear} params - Parameters for clearing storage
+	* @param {string} [params.storage] - Name of the storage to clear, defaults to 'default'
+	* @returns {Promise<void>} A promise that resolves when the storage is cleared
+	*/
+	async clear({ storage }) {
+		this.getStorage(storage)?.clear();
+	}
+	/**
+	* Gets the number of items in the specified storage
+	* @param {StorageTypes.Size} params - Parameters for getting storage size
+	* @param {string} [params.storage] - Name of the storage to get size of, defaults to 'default'
+	* @returns {Promise<number>} A promise that resolves with the number of items
+	*/
+	async size({ storage }) {
+		return this.getStorage(storage)?.size() ?? 0;
+	}
+	/**
+	* Initializes the storage manager
+	* @returns {Promise<void>} A promise that resolves when the storage manager is initialized
+	*/
+	async init() {}
+};
+//#endregion
+export { NitroStorageManager };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vercube/nitro",
+  "version": "1.0.0-beta.1",
+  "description": "Nitro module for Vercube framework",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercube/vercube.git",
+    "directory": "packages/nitro"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./runtime/handler": "./dist/runtime/RouteHandler.mjs"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "vercube",
+    "nitro",
+    "framework"
+  ],
+  "dependencies": {
+    "chokidar": "5.0.0",
+    "defu": "6.1.7",
+    "nitro": "3.0.260610-beta",
+    "oxc-parser": "0.135.0",
+    "pathe": "2.0.3",
+    "tinyglobby": "0.2.17",
+    "@vercube/core": "1.0.0-beta.1",
+    "@vercube/di": "1.0.0-beta.1",
+    "@vercube/storage": "1.0.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config ./tsdown.config.ts --config-loader=unrun"
+  }
+}