nitro

por sentry

Build and deploy universal JavaScript servers with Nitro v3. Use when working with nitro.config.ts, defineNitroConfig, defineHandler, defineConfig, server.ts…

npx skills add https://github.com/getsentry/junior --skill nitro

Baixar ZIP GitHub

336

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

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

Step 3: Implement

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

Step 4: Validate

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

Step 5: Troubleshoot

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