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