nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/builder.d.mts

@@ -1,28 +1,15 @@
 import { t as NitroDevApp } from "./_dev.mjs";
-import { IncomingMessage, OutgoingMessage } from "node:http";
-import { Duplex } from "node:stream";
+import { RunnerMessageListener, RunnerRPCHooks } from "env-runner";
+import { IncomingMessage } from "node:http";
+import { Socket } from "node:net";
 import { Server, ServerOptions } from "srvx";
-import { LoadConfigOptions, Nitro, NitroBuildInfo, NitroConfig, NitroOptions, RunnerMessageListener, RunnerRPCHooks, TaskEvent, TaskRunnerOptions } from "nitro/types";
-
-//#region src/nitro.d.ts
+import { LoadConfigOptions, Nitro, NitroBuildInfo, NitroConfig, NitroOptions, TaskEvent, TaskRunnerOptions } from "nitro/types";
 declare function createNitro(config?: NitroConfig, opts?: LoadConfigOptions): Promise<Nitro>;
-//#endregion
-//#region src/config/loader.d.ts
 declare function loadOptions(configOverrides?: NitroConfig, opts?: LoadConfigOptions): Promise<NitroOptions>;
-//#endregion
-//#region src/build/build.d.ts
 declare function build(nitro: Nitro): Promise<void>;
-//#endregion
-//#region src/build/assets.d.ts
 declare function copyPublicAssets(nitro: Nitro): Promise<void>;
-//#endregion
-//#region src/build/prepare.d.ts
 declare function prepare(nitro: Nitro): Promise<void>;
-//#endregion
-//#region src/build/types.d.ts
 declare function writeTypes(nitro: Nitro): Promise<void>;
-//#endregion
-//#region src/build/info.d.ts
 declare function getBuildInfo(root: string): Promise<{
   outputDir?: undefined;
   buildInfo?: undefined;
@@ -30,13 +17,11 @@ declare function getBuildInfo(root: string): Promise<{
   outputDir: string;
   buildInfo?: NitroBuildInfo;
 }>;
-//#endregion
-//#region src/dev/server.d.ts
 declare function createDevServer(nitro: Nitro): NitroDevServer;
 declare class NitroDevServer extends NitroDevApp implements RunnerRPCHooks {
   #private;
   constructor(nitro: Nitro);
-  upgrade(req: IncomingMessage, socket: OutgoingMessage<IncomingMessage> | Duplex, head: any): Promise<any>;
+  upgrade(req: IncomingMessage, socket: Socket, head: any): Promise<void>;
   listen(opts?: Partial<Omit<ServerOptions, "fetch">>): Server;
   close(): Promise<void>;
   reload(): void;
@@ -44,11 +29,7 @@ declare class NitroDevServer extends NitroDevApp implements RunnerRPCHooks {
   onMessage(listener: RunnerMessageListener): void;
   offMessage(listener: RunnerMessageListener): void;
 }
-//#endregion
-//#region src/prerender/prerender.d.ts
 declare function prerender(nitro: Nitro): Promise<void>;
-//#endregion
-//#region src/task.d.ts
 /** @experimental */
 declare function runTask(taskEvent: TaskEvent, opts?: TaskRunnerOptions): Promise<{
   result: unknown;
@@ -59,5 +40,4 @@ declare function listTasks(opts?: TaskRunnerOptions): Promise<Record<string, {
     description: string;
   };
 }>>;
-//#endregion
 export { build, copyPublicAssets, createDevServer, createNitro, getBuildInfo, listTasks, loadOptions, prepare, prerender, runTask, writeTypes };

package/dist/builder.mjs

@@ -1,9 +1,4 @@
-import "./_common.mjs";
-import { D as prepare, M as build, O as copyPublicAssets, _ as writeTypes, m as getBuildInfo } from "./_build/common.mjs";
-import "./_libs/rc9+c12+dotenv.mjs";
+import { D as copyPublicAssets, E as prepare, _ as writeTypes, j as build, m as getBuildInfo } from "./_build/common.mjs";
 import { a as loadOptions, i as createNitro, n as runTask, r as prerender, t as listTasks } from "./_chunks/nitro.mjs";
-import "./_libs/tsconfck.mjs";
-import "./_chunks/nitro2.mjs";
-import { n as createDevServer } from "./_chunks/dev.mjs";
-
-export { build, copyPublicAssets, createDevServer, createNitro, getBuildInfo, listTasks, loadOptions, prepare, prerender, runTask, writeTypes };
+import { n as createDevServer } from "./_dev.mjs";
+export { build, copyPublicAssets, createDevServer, createNitro, getBuildInfo, listTasks, loadOptions, prepare, prerender, runTask, writeTypes };

package/dist/cli/_chunks/build.mjs

@@ -1,33 +1,32 @@
-import { ct as resolve } from "../../_build/common.mjs";
+import { dt as resolve } from "../../_build/common.mjs";
 import { t as defineCommand } from "../../_libs/citty.mjs";
 import { t as commonArgs } from "./common.mjs";
 import { build, copyPublicAssets, createNitro, prepare, prerender } from "nitro/builder";
-
-//#region src/cli/commands/build.ts
+const buildArgs = {
+	...commonArgs,
+	minify: {
+		type: "boolean",
+		description: "Minify the output (overrides preset defaults you can also use `--no-minify` to disable)."
+	},
+	preset: {
+		type: "string",
+		description: "The build preset to use (you can also use `NITRO_PRESET` environment variable)."
+	},
+	builder: {
+		type: "string",
+		description: "The builder to use (you can also use `NITRO_BUILDER` environment variable)."
+	},
+	compatibilityDate: {
+		type: "string",
+		description: "The date to use for preset compatibility (you can also use `NITRO_COMPATIBILITY_DATE` environment variable)."
+	}
+};
 var build_default = defineCommand({
 	meta: {
 		name: "build",
 		description: "Build nitro project for production"
 	},
-	args: {
-		...commonArgs,
-		minify: {
-			type: "boolean",
-			description: "Minify the output (overrides preset defaults you can also use `--no-minify` to disable)."
-		},
-		preset: {
-			type: "string",
-			description: "The build preset to use (you can also use `NITRO_PRESET` environment variable)."
-		},
-		builder: {
-			type: "string",
-			description: "The builder to use (you can also use `NITRO_BUILDER` environment variable)."
-		},
-		compatibilityDate: {
-			type: "string",
-			description: "The date to use for preset compatibility (you can also use `NITRO_COMPATIBILITY_DATE` environment variable)."
-		}
-	},
+	args: buildArgs,
 	async run({ args }) {
 		const nitro = await createNitro({
 			rootDir: resolve(args.dir || args._dir || "."),
@@ -43,6 +42,4 @@ var build_default = defineCommand({
 		await nitro.close();
 	}
 });
-
-//#endregion
-export { build_default as default };
+export { buildArgs, build_default as default };

package/dist/cli/_chunks/common.mjs

@@ -1,4 +1,3 @@
-//#region src/cli/common.ts
 const commonArgs = {
 	dir: {
 		type: "string",
@@ -10,6 +9,4 @@ const commonArgs = {
 		description: "project root directory (prefer using `--dir`)"
 	}
 };
-
-//#endregion
-export { commonArgs as t };
+export { commonArgs as t };

package/dist/cli/_chunks/deploy.mjs

@@ -0,0 +1,37 @@
+import { dt as resolve, m as getBuildInfo, ut as relative } from "../../_build/common.mjs";
+import { t as defineCommand } from "../../_libs/citty.mjs";
+import build_default, { buildArgs } from "./build.mjs";
+import consola from "consola";
+import { execSync } from "node:child_process";
+var deploy_default = defineCommand({
+	meta: {
+		name: "deploy",
+		description: "Build and deploy nitro project for production"
+	},
+	args: {
+		...buildArgs,
+		prebuilt: {
+			type: "boolean",
+			description: "Skip the build step and deploy the existing build"
+		}
+	},
+	async run(ctx) {
+		globalThis.__nitroDeploying__ = true;
+		if (!ctx.args.prebuilt) await build_default.run(ctx);
+		if (globalThis.__nitroDeployed__) return;
+		const { buildInfo, outputDir } = await getBuildInfo(resolve(ctx.args.dir || ctx.args._dir || "."));
+		if (!buildInfo) {
+			consola.error("No build info found, cannot deploy.");
+			process.exit(1);
+		}
+		if (!buildInfo.commands?.deploy) {
+			consola.error(`The \`${buildInfo.preset}\` preset does not have a default deploy command.\n\nTry using a different preset with the \`--preset\` option, or configure a deploy command in the Nitro config, or deploy manually.`);
+			process.exit(1);
+		}
+		const extraArgs = ctx.rawArgs.indexOf("--") !== -1 ? ctx.rawArgs.slice(ctx.rawArgs.indexOf("--") + 1).join(" ") : "";
+		const deployCommand = buildInfo.commands.deploy.replace(/([\s:])\.\/(\S*)/g, `$1${relative(process.cwd(), outputDir)}/$2`) + (extraArgs ? ` ${extraArgs}` : "");
+		consola.info(`$ ${deployCommand}`);
+		execSync(deployCommand, { stdio: "inherit" });
+	}
+});
+export { deploy_default as default };

package/dist/cli/_chunks/dev.mjs

@@ -1,12 +1,9 @@
-import { ct as resolve } from "../../_build/common.mjs";
-import "../../_libs/rc9+c12+dotenv.mjs";
-import { t as NitroDevServer } from "../../_chunks/dev.mjs";
+import { dt as resolve } from "../../_build/common.mjs";
+import { t as NitroDevServer } from "../../_dev.mjs";
 import { t as defineCommand } from "../../_libs/citty.mjs";
 import { t as commonArgs } from "./common.mjs";
-import { consola } from "consola";
+import { consola as consola$1 } from "consola";
 import { build, createNitro, prepare } from "nitro/builder";
-
-//#region src/cli/commands/dev.ts
 const hmrKeyRe = /^runtimeConfig\.|routeRules\./;
 var dev_default = defineCommand({
 	meta: {
@@ -29,7 +26,7 @@ var dev_default = defineCommand({
 		let nitro;
 		const reload = async () => {
 			if (nitro) {
-				consola.info("Restarting dev server...");
+				consola$1.info("Restarting dev server...");
 				if ("unwatch" in nitro.options._c12) await nitro.options._c12.unwatch();
 				await nitro.close();
 			}
@@ -42,7 +39,7 @@ var dev_default = defineCommand({
 				c12: { async onUpdate({ getDiff, newConfig }) {
 					const diff = getDiff();
 					if (diff.length === 0) return;
-					consola.info("Nitro config updated:\n" + diff.map((entry) => `  ${entry.toString()}`).join("\n"));
+					consola$1.info("Nitro config updated:\n" + diff.map((entry) => `  ${entry.toString()}`).join("\n"));
 					await (diff.every((e) => hmrKeyRe.test(e.key)) ? nitro.updateConfig(newConfig.config || {}) : reload());
 				} }
 			});
@@ -57,6 +54,4 @@ var dev_default = defineCommand({
 		await reload();
 	}
 });
-
-//#endregion
-export { dev_default as default };
+export { dev_default as default };

package/dist/cli/_chunks/docs.mjs

@@ -0,0 +1,28 @@
+import { t as defineCommand } from "../../_libs/citty.mjs";
+import { docsDir } from "nitro/meta";
+import { execSync } from "node:child_process";
+var docs_default = defineCommand({
+	meta: {
+		name: "docs",
+		description: "Explore Nitro documentation"
+	},
+	args: { page: {
+		type: "string",
+		description: "Page path to open"
+	} },
+	run({ rawArgs }) {
+		const runnerCmd = ([
+			["bun", "x"],
+			["pnpm", "dlx"],
+			["npm", "x"]
+		].find(([pkg]) => {
+			try {
+				execSync(`${pkg} -v`, { stdio: "ignore" });
+				return true;
+			} catch {}
+		}) || ["npm", "x"]).join(" ");
+		const args = rawArgs?.join(" ") || "";
+		execSync(`${runnerCmd} mdzilla ${docsDir}${args ? ` ${args}` : ""}`, { stdio: "inherit" });
+	}
+});
+export { docs_default as default };

package/dist/cli/_chunks/list.mjs

@@ -1,9 +1,7 @@
-import { ct as resolve } from "../../_build/common.mjs";
+import { dt as resolve } from "../../_build/common.mjs";
 import { t as defineCommand } from "../../_libs/citty.mjs";
-import { consola } from "consola";
+import { consola as consola$1 } from "consola";
 import { listTasks, loadOptions } from "nitro/builder";
-
-//#region src/cli/commands/task/list.ts
 var list_default = defineCommand({
 	meta: {
 		name: "run",
@@ -19,9 +17,7 @@ var list_default = defineCommand({
 			cwd,
 			buildDir: (await loadOptions({ rootDir: cwd }).catch(() => void 0))?.buildDir || ".nitro"
 		});
-		for (const [name, task] of Object.entries(tasks)) consola.log(` - \`${name}\`${task.meta?.description ? ` - ${task.meta.description}` : ""}`);
+		for (const [name, task] of Object.entries(tasks)) consola$1.log(` - \`${name}\`${task.meta?.description ? ` - ${task.meta.description}` : ""}`);
 	}
 });
-
-//#endregion
-export { list_default as default };
+export { list_default as default };

package/dist/cli/_chunks/prepare.mjs

@@ -1,9 +1,7 @@
-import { ct as resolve } from "../../_build/common.mjs";
+import { dt as resolve } from "../../_build/common.mjs";
 import { t as defineCommand } from "../../_libs/citty.mjs";
 import { t as commonArgs } from "./common.mjs";
 import { createNitro, writeTypes } from "nitro/builder";
-
-//#region src/cli/commands/prepare.ts
 var prepare_default = defineCommand({
 	meta: {
 		name: "prepare",
@@ -14,6 +12,4 @@ var prepare_default = defineCommand({
 		await writeTypes(await createNitro({ rootDir: resolve(args.dir || args._dir || ".") }));
 	}
 });
-
-//#endregion
-export { prepare_default as default };
+export { prepare_default as default };

package/dist/cli/_chunks/preview.mjs

@@ -0,0 +1,48 @@
+import { dt as resolve } from "../../_build/common.mjs";
+import { t as defineCommand } from "../../_libs/citty.mjs";
+import { t as startPreview } from "../../_chunks/nitro4.mjs";
+import { t as commonArgs } from "./common.mjs";
+import { serve } from "srvx";
+import { log } from "srvx/log";
+var preview_default = defineCommand({
+	meta: {
+		name: "preview",
+		description: "Start a local server to preview the built server"
+	},
+	args: {
+		...commonArgs,
+		port: {
+			type: "string",
+			description: "specify port"
+		},
+		host: {
+			type: "string",
+			description: "specify hostname"
+		}
+	},
+	async run({ args }) {
+		const rootDir = resolve(args.dir || args._dir || ".");
+		const server = serve({
+			fetch(req) {
+				return preview.fetch(req);
+			},
+			middleware: [log()],
+			gracefulShutdown: false,
+			port: args.port,
+			hostname: args.host
+		});
+		const preview = await startPreview({
+			rootDir,
+			loader: { srvxServer: server }
+		});
+		if (preview.upgrade) server.node?.server?.on("upgrade", (req, socket, head) => {
+			preview.upgrade(req, socket, head);
+		});
+		process.on("SIGINT", async () => {
+			await server.close();
+			await preview.close();
+			process.exit(0);
+		});
+	}
+});
+export { preview_default as default };

package/dist/cli/_chunks/run.mjs

@@ -1,10 +1,8 @@
-import { ct as resolve } from "../../_build/common.mjs";
+import { dt as resolve } from "../../_build/common.mjs";
 import { t as defineCommand } from "../../_libs/citty.mjs";
-import { consola } from "consola";
+import { consola as consola$1 } from "consola";
 import destr from "destr";
 import { loadOptions, runTask } from "nitro/builder";
-
-//#region src/cli/commands/task/run.ts
 var run_default = defineCommand({
 	meta: {
 		name: "run",
@@ -28,10 +26,10 @@ var run_default = defineCommand({
 	async run({ args }) {
 		const cwd = resolve(args.dir || args.cwd || ".");
 		const options = await loadOptions({ rootDir: cwd }).catch(() => void 0);
-		consola.info(`Running task \`${args.name}\`...`);
+		consola$1.info(`Running task \`${args.name}\`...`);
 		let payload = destr(args.payload || "{}");
 		if (typeof payload !== "object") {
-			consola.error(`Invalid payload: \`${args.payload}\` (it should be a valid JSON object)`);
+			consola$1.error(`Invalid payload: \`${args.payload}\` (it should be a valid JSON object)`);
 			payload = void 0;
 		}
 		try {
@@ -43,13 +41,11 @@ var run_default = defineCommand({
 				cwd,
 				buildDir: options?.buildDir || ".nitro"
 			});
-			consola.success("Result:", result);
+			consola$1.success("Result:", result);
 		} catch (error) {
-			consola.error(`Failed to run task \`${args.name}\`: ${error}`);
+			consola$1.error(`Failed to run task \`${args.name}\`: ${error}`);
 			process.exit(1);
 		}
 	}
 });
-
-//#endregion
-export { run_default as default };
+export { run_default as default };

package/dist/cli/_chunks/task.mjs

@@ -1,6 +1,4 @@
 import { t as defineCommand } from "../../_libs/citty.mjs";
-
-//#region src/cli/commands/task/index.ts
 var task_default = defineCommand({
 	meta: {
 		name: "task",
@@ -11,6 +9,4 @@ var task_default = defineCommand({
 		run: () => import("./run.mjs").then((r) => r.default)
 	}
 });
-
-//#endregion
-export { task_default as default };
+export { task_default as default };

package/dist/cli/index.mjs

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { n as runMain, t as defineCommand } from "../_libs/citty.mjs";
 import { version } from "nitro/meta";
-
-//#region src/cli/index.ts
 runMain(defineCommand({
 	meta: {
 		name: "nitro",
@@ -12,10 +10,11 @@ runMain(defineCommand({
 	subCommands: {
 		dev: () => import("./_chunks/dev.mjs").then((r) => r.default),
 		build: () => import("./_chunks/build.mjs").then((r) => r.default),
+		deploy: () => import("./_chunks/deploy.mjs").then((r) => r.default),
 		prepare: () => import("./_chunks/prepare.mjs").then((r) => r.default),
-		task: () => import("./_chunks/task.mjs").then((r) => r.default)
+		task: () => import("./_chunks/task.mjs").then((r) => r.default),
+		preview: () => import("./_chunks/preview.mjs").then((r) => r.default),
+		docs: () => import("./_chunks/docs.mjs").then((r) => r.default)
 	}
 }));
-
-//#endregion
-export {  };
+export {};

package/dist/docs/0.docs/0.index/index.md

@@ -0,0 +1,56 @@
+# Introduction
+
+> Nitro is a full-stack server framework, compatible with any runtime and any deployment target.
+
+Nitro gives you a production-ready server with filesystem routing, code-splitting, and built-in support for storage, caching, and databases — all runtime-agnostic and deployable anywhere.
+
+## What is Nitro?
+
+Create server and API routes inside the `routes/` directory. Each file maps directly to a URL path, and Nitro handles the rest — routing, code-splitting, and optimized builds.
+
+You can also take full control of the server entry by creating a `server.ts` file. Nitro’s high-level, runtime-agnostic approach lets you use any HTTP library, such as [Elysia](https://elysiajs.com/), [h3](https://h3.dev), or [Hono](https://hono.dev).
+
+### Performance
+
+Nitro compiles your routes at build time, removing the need for a runtime router. Only the code required to handle each incoming request is loaded and executed. This makes it ideal for serverless hosting, with near-0ms boot time regardless of project size.
+
+### Deploy Anywhere
+
+Build your server into an optimized `.output/` folder compatible with Node.js, Bun, Deno, and many hosting platforms without any configuration — Cloudflare Workers, Netlify, Vercel, and more. Take advantage of platform features like ESR, ISR, and SWR without changing a single line of code.
+
+### Server-Side Rendering
+
+Render HTML with your favorite templating engine, or use component libraries such as React, Vue, or Svelte directly on the server. Go full universal rendering with client-side hydration. Nitro provides the foundation and a progressive approach to reach your goals.
+
+### Storage
+
+Nitro includes a runtime-agnostic key-value storage layer out of the box. It uses in-memory storage by default, but you can connect more than 20 different drivers (FS, Redis, S3, etc.), attach them to different namespaces, and swap them without changing your code.
+
+### Caching
+
+Nitro supports caching for both server routes and server functions, backed directly by the server storage (via the `cache` namespace).
+
+### Database
+
+Nitro also includes a built-in SQL database. It defaults to SQLite, but you can connect to and query more than 10 databases (Postgres, MySQL, PGLite, etc.) using the same API.
+
+### Meta-Framework Foundation
+
+Nitro can be used as the foundation for building your own meta-framework. Popular frameworks such as Nuxt, SolidStart, and TanStack Start fully or partially leverage Nitro.
+
+## Vite Integration
+
+Nitro integrates seamlessly with [Vite](https://vite.dev) as a plugin. If you’re building a frontend application with Vite, adding Nitro gives you API routes, server-side rendering, and a full production server — all built together with `vite build`.
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+  plugins: [nitro()],
+});
+```
+
+With Nitro, `vite build` produces an optimized `.output/` folder containing both your frontend and backend — ready to deploy anywhere.
+
+Ready to give it a try? Jump into the [quick start](/docs/quick-start).

package/dist/docs/0.docs/1.quick-start.md

@@ -0,0 +1,110 @@
+# Quick Start
+
+> Start with a fresh Nitro project or adopt it in your current Vite project.
+
+## Try Nitro online
+
+Get a taste of Nitro in your browser using our playground.
+
+[Play with Nitro in StackBlitz](https://stackblitz.com/github/nitrojs/starter/tree/v3-vite?file=index.html,server.ts)
+
+## Create a Nitro project
+
+The fastest way to create a Nitro application is using the `create-nitro-app`.
+
+> [!NOTE]
+> Make sure to have installed the latest LTS version of either [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
+
+<pm-x></pm-x>
+
+Follow the instructions from the CLI and you will be ready to start your development server.
+
+## Add to a Vite project
+
+You can add Nitro to any existing Vite project to get API routes, server-side rendering, and more.
+
+<steps>
+
+### Install `nitro` and `vite`
+
+<pm-install></pm-install>
+
+### Add Nitro plugin to Vite
+
+Add the Nitro plugin to your `vite.config.ts`:
+
+```ts [vite.config.ts] {2,6}
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+  plugins: [
+    nitro()
+  ],
+});
+```
+
+### Configure Nitro
+
+Create a `nitro.config.ts` to configure the server directory:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./server",
+});
+```
+
+The `serverDir` option tells Nitro where to look for your server routes. In this example, all routes will be inside the `server/` directory.
+
+### Create an API route
+
+Create your first API route at `server/api/test.ts`:
+
+<code-tree>
+
+```ts [server/api/test.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(() => {
+  return { message: "Hello Nitro!" };
+});
+```
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./server",
+});
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+  plugins: [nitro()],
+});
+```
+</code-tree>
+
+The file path maps directly to the route URL — `server/api/test.ts` becomes `/api/test`.
+
+<tip>
+
+As an alternative to filesystem routing, you can declare routes programmatically using the `routes` config option. See [Programmatic route handlers](/docs/routing#programmatic-route-handlers) for more details.
+</tip>
+
+<tip>
+
+You can return strings, JSON objects, `Response` instances, or readable streams from your handlers. See [Routing](/docs/routing) for more about dynamic routes, methods, and middleware.
+</tip>
+
+### Start the development server
+
+<pm-run></pm-run>
+
+Your API route is now accessible at `http://localhost:3000/api/test` :sparkles:
+</steps>