No native build steps or pod installs are required. All packages are pure JavaScript/TypeScript.

Project setup

1. Copy the source/ directory into your project root, e.g. ./nitro-src/.
2. In tsconfig.json, add path aliases so your code can resolve the internal modules:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "nitro-src/*": ["./nitro-src/*"]
    },
    "moduleResolution": "Bundler",
    "target": "ESNext",
    "module": "ESNext"
  }
}

3. Ensure "type": "module" is set in your package.json because the source uses ESM throughout.
4. Set required environment variables before running the dev server:

# Optional: override the preset used for builds
NITRO_PRESET=node

# Optional: root directory of the project
NITRO_ROOT=./

5. To run the CLI directly from source, point your package.json script at the CLI entry:

{
  "scripts": {
    "dev": "tsx nitro-src/cli/index.ts dev",
    "build": "tsx nitro-src/cli/index.ts build"
  }
}

6. Import the public type index in any file that needs Nitro's type augmentations:

import "nitro-src/types/index.ts";

Public API

resolvePreset

import { resolvePreset } from "nitro-src/presets/index.ts";

function resolvePreset(name: PresetNameInput, opts?: PresetOptions): Promise<NitroPreset>;

Resolves a named deployment preset (e.g. "cloudflare", "aws-lambda", "node") to its full preset object. Call this when building a custom build pipeline that needs to select the output target dynamically, such as when reading NITRO_PRESET from the environment and applying the matching adapter configuration.

PresetName / PresetNameInput

import type { PresetName, PresetNameInput, PresetOptions } from "nitro-src/presets/index.ts";

type PresetNameInput = PresetName | (string & {});

Union of all valid preset name literals plus an open string for custom presets. Use PresetNameInput for function parameters that accept a preset identifier, and PresetName when you want strict validation of known platform targets.

defineCommand (CLI integration)

import { defineCommand } from "citty";
// Nitro's CLI is composed of citty commands wired in cli/index.ts
// Each subcommand is a lazy-loaded citty command definition.

const cmd = defineCommand({
  meta: { name: "my-cmd", description: "..." },
  async run(ctx) { /* ... */ },
});

The CLI tree in cli/index.ts uses defineCommand from citty. When extending or embedding the Nitro CLI into your own tooling, import defineCommand and compose commands the same way Nitro does, then pass them as subCommands entries.

Working examples

Scenario - Resolving a deployment preset at build time

A custom build script reads the target platform from an environment variable and retrieves the matching Nitro preset configuration before invoking the bundler.

import { resolvePreset } from "./nitro-src/presets/index.ts";
import type { PresetNameInput } from "./nitro-src/presets/index.ts";

async function getBuildPreset(): Promise<void> {
  const presetName: PresetNameInput =
    (process.env.NITRO_PRESET as PresetNameInput) ?? "node";

  const preset = await resolvePreset(presetName);
  console.log("Resolved preset:", preset);
  // Pass `preset` into your Nitro build configuration
}

getBuildPreset();

Scenario - Importing all Nitro types for a typed server handler

Augment the global Nitro type environment in one import so that defineEventHandler, H3Event, and runtime-config types are all available project-wide.

// server/types.ts  – import once, augments globals for the whole project
import "nitro-src/types/index.ts";

// server/routes/hello.ts
import type { EventHandler } from "h3";

const handler: EventHandler = (event) => {
  return { message: "hello from typed Nitro route" };
};

export default handler;

Scenario - Embedding the Nitro CLI inside a monorepo toolchain

A monorepo root script wires the Nitro CLI subcommands into a larger Citty-based CLI so developers run a single tool binary for all operations.

import { defineCommand, runMain } from "citty";

const main = defineCommand({
  meta: { name: "tool", description: "Monorepo toolchain" },
  subCommands: {
    // Lazy-load Nitro's own subcommands
    dev: () =>
      import("./nitro-src/cli/commands/dev.ts").then((r) => r.default),
    build: () =>
      import("./nitro-src/cli/commands/build.ts").then((r) => r.default),
    task: () =>
      import("./nitro-src/cli/commands/task/index.ts").then((r) => r.default),
    // Add custom project commands alongside
    lint: () => import("./tools/lint.ts").then((r) => r.default),
  },
});

runMain(main);

File walkthrough

• cli/index.ts - Entry point for the nitro binary; wires all subcommands via citty's defineCommand / runMain.
• cli/common.ts - Shared CLI utilities (argument parsing helpers, logger setup).
• cli/commands/build.ts - nitro build command implementation.
• cli/commands/dev.ts - nitro dev command; starts the development server with HMR.
• cli/commands/deploy.ts - nitro deploy command for platform deployments.
• cli/commands/prepare.ts - nitro prepare command; generates type stubs.
• cli/commands/preview.ts - nitro preview command; serves the built output locally.
• cli/commands/docs.ts - Opens Nitro documentation in the browser.
• cli/commands/task/index.ts - Parent task command grouping list and run subcommands.
• cli/commands/task/list.ts - Lists registered server tasks.
• cli/commands/task/run.ts - Runs a named server task with optional payload.
• config/defaults.ts - Default configuration values applied before user config.
• config/loader.ts - Loads and merges nitro.config.ts / nuxt.config.ts configuration.
• config/update.ts - Applies incremental config updates at dev-reload time.
• config/resolvers/ - One resolver per concern (paths, storage, database, assets, route rules, etc.) applied in sequence during config normalization.
• dev/app.ts - Vite-backed development app server with middleware chain.
• dev/server.ts - Dev server lifecycle (start, stop, reload).
• dev/vfs.ts - Virtual file system used during development to serve generated files.
• prerender/prerender.ts - Crawls routes and writes static HTML output.
• prerender/utils.ts - URL normalization and route filtering helpers for pre-rendering.
• presets/_nitro/ - Internal base preset shared by all platform presets.
• presets/_static/ - Static file serving preset.
• presets/_utils/ - Shared preset utility functions.
• presets/index.ts - Public re-export of resolvePreset and preset types.
• presets/<platform>/ - One directory per deployment target containing preset config and runtime shims.
• runtime/ - Code bundled into the server output: request handling, storage, caching, task scheduling.
• types/index.ts - Barrel that re-exports all Nitro type definitions and triggers module augmentation.
• types/fetch/ - Typed $fetch utilities including match helpers and serialization types.
• builder.ts - Orchestrates the Rolldown bundle pipeline for production builds.
• global.ts - Side-effectful global augmentation (adds Nitro globals to the TypeScript environment).
• module.ts - API for authoring Nitro modules (plugin system for config-time extensions).
• nitro.ts - createNitro factory and Nitro instance management.
• preview.ts - Launches a local preview of the production build output.
• routing.ts - Maps scanned handler files to H3 router entries.
• scan.ts - Walks server/routes, server/middleware, server/plugins, and server/tasks directories.
• task.ts - Defines the server-side task runner (schedule / run named async jobs).
• vite.ts - Exposes Nitro as a Vite plugin for framework integration.

Common pitfalls and fixes

• ESM-only source: The source uses top-level import/export with .ts extensions; ensure "type": "module" in package.json and use tsx or a bundler that handles .ts imports.
• nitro/meta import at CLI startup: cli/index.ts imports nitro/meta for the version string; add "nitro/meta" to your tsconfig paths or install the nitro package alongside the source copy.
• Rolldown peer requirement: builder.ts uses rolldown (not Rollup); pin rolldown to the exact version listed in the upstream package.json to avoid API mismatches.
• Preset types not generated: types/_types.gen.ts is a generated file; run nitro prepare once to materialize it before TypeScript compilation.
• db0 dialect imports: The database resolver imports dialect-specific drivers from db0; install only the connectors you actually use to avoid missing optional native modules.
• Module resolution mode: Set "moduleResolution": "Bundler" (not "Node16") in tsconfig.json; several internal imports rely on extensionless resolution that Node16 rejects.

Vibe-coding prompt template

I have a copy of the Nitro v3 server framework source located at `./nitro-src/`
and a USAGE.md guide at `./USAGE.md`. The upstream package is `user@example.com`.

My project is a Node.js TypeScript application using [describe your stack].

Please help me integrate Nitro step-by-step:

1. Read `USAGE.md` sections "Project setup" and "Public API" first.
2. Wire `./nitro-src/types/index.ts` so TypeScript picks up all Nitro type augmentations.
3. Use `resolvePreset` from `./nitro-src/presets/index.ts` to select the correct
   deployment target based on my `NITRO_PRESET` environment variable.
4. Embed the Nitro CLI commands from `./nitro-src/cli/commands/` into my existing
   Citty CLI, adding `dev`, `build`, and `task` subcommands.
5. Show me how to define a server route handler that is correctly typed using
   the types exported from `./nitro-src/types/`.
6. Point out any `tsconfig.json` or `package.json` changes needed.
7. Flag any pitfalls from the "Common pitfalls and fixes" section that apply.

Work only with symbols and file paths documented in USAGE.md; do not invent APIs.

License and credit

Nitro is released under the MIT License (see source/LICENSE if present, or the upstream repository). Source and full documentation are available at https://github.com/nitrojs/nitro and https://nitro.build. Upstream package: nitro on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Nitro: Production-Ready Vite Server Framework

Automation, Utilities & Developer Tools

Free