# Nitro

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

- Skill: `getsentry/nitro` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add getsentry/nitro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/getsentry/nitro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Sentry (https://skillmd.com/u/getsentry)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/getsentry/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`.