nitro

Build, configure, and deploy Nitro v3 applications using correct APIs and patterns.

Step 1: Classify the request

Request type	Read first
API surface, handler signatures, imports, config options	references/api-surface.md
Setup, routing, caching, storage, plugins, frameworks, common patterns	references/common-use-cases.md
Build failures, runtime errors, deployment issues, migration from v2	references/troubleshooting-workarounds.md

Load only the reference(s) matching the request. If the task spans categories, load relevant files.

Step 2: Apply core guardrails

1. Import defineHandler from "nitro", not defineEventHandler (v2 API).
2. Import config helpers from subpaths: "nitro/config", "nitro/cache", "nitro/storage", "nitro/database", "nitro/runtime-config", "nitro/types".
3. Use web standard event.req (Request) for body/headers — not v2 utilities like readBody or getHeader.
4. Never return from middleware unless intentionally terminating the request.
5. Only GET/HEAD requests are cached by defineCachedHandler; other methods bypass automatically.
6. useDatabase and defineTask require experimental feature flags.
7. Use "nitro" package name, not "nitropack" (v2).

Step 3: Implement

1. For new projects, use defineConfig from "nitro" in nitro.config.ts or add nitro() plugin from "nitro/vite" to vite.config.ts.
2. For server entry, export a web-compatible fetch(Request): Response handler from server.ts, or use server.node.ts for Express/Fastify.
3. For filesystem routes, place handlers in routes/ or api/ with [param] for dynamic segments and .get.ts/.post.ts for method-specific routes.
4. For caching, use defineCachedHandler from "nitro/cache" with maxAge and swr options.
5. For storage, use useStorage(namespace) from "nitro/storage" and configure drivers via storage config.
6. For plugins, create files in plugins/ directory using definePlugin and hook into request, response, error, or close.
7. For deployment, set preset in config or use NITRO_PRESET env var; Vercel/Netlify/Cloudflare are auto-detected.

Step 4: Validate

1. Run nitro dev and verify routes respond correctly.
2. Run nitro build and check .output/server/ contains expected files.
3. For cached routes, verify cache headers (etag, cache-control) and 304 responses.
4. For storage, verify data persists across requests with configured driver.
5. For deployment, verify the preset produces correct output format.

Step 5: Troubleshoot

1. defineEventHandler is not defined → use defineHandler from "nitro" (v3 API).
2. Cannot find module 'nitropack' → rename to "nitro" in imports and package.json.
3. Route not matched → check file is in routes/ or api/, or verify routes config mapping.
4. Middleware returning responses unexpectedly → ensure middleware does not return a value.
5. For detailed diagnostics, read references/troubleshooting-workarounds.md.