nitro

---
name: nitro
description: Build and deploy universal JavaScript servers with Nitro v3. Use when working with nitro.config.ts, defineNitroConfig, defineHandler, defineConfig, server.ts entry, filesystem routing, route rules, useStorage, defineCachedHandler, useDatabase, definePlugin, runtime hooks, Vercel/Cloudflare deployment, or migrating from Nitro v2/nitropack.
license: Apache-2.0
---

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`.