English for Nitro Developers
Vocabulary for developers building servers with Nitro (UnJS) — universal deployment, server routes, and the Nitro build pipeline — for teams discussing framework-agnostic backends in English.
Nitro is a UnJS server toolkit that powers Nuxt’s backend and can also run standalone — it builds one server codebase and deploys it, unmodified, to Node, serverless platforms, edge runtimes, or a static host. Because the same code targets very different runtimes, deployment vocabulary and server vocabulary get discussed together constantly. Here’s the English for talking about it clearly with your team.
Universal Deployment
Universal deployment — Nitro’s core promise: write server code once, and target multiple runtimes (Node, Deno, Cloudflare Workers, Vercel, AWS Lambda) by changing a build preset, not the code.
“We’re not rewriting the API for the edge — we’re just changing the deployment preset; the route handlers stay identical.”
Preset — the specific build configuration Nitro uses to produce output tailored to one deployment target.
“Switch the preset to cloudflare-pages before you debug the cold-start issue — you’re currently testing against the Node preset, which behaves differently.”
Runtime-agnostic — code written without assuming a specific JavaScript runtime’s APIs are available, so it can run unmodified across Node, Deno, and edge environments.
“Don’t reach for Node’s fs module directly in that handler — it’s not runtime-agnostic, and it’ll break the moment we deploy to an edge preset.”
Server Routes and Handlers
Server route — a file-based API endpoint defined by its location in the server/routes (or server/api) directory, similar in spirit to Next.js API routes.
“Add a new server route for that instead of bolting it onto an existing handler — keep the file-based routing clean and predictable.”
Event handler — the function signature Nitro expects for a route, receiving a normalized H3Event object regardless of the underlying runtime’s native request/response types.
“You’re accessing the raw Node request object directly — go through the event handler’s helpers instead, or it won’t work once we’re on the edge preset.”
H3 — the lightweight HTTP framework underlying Nitro’s routing and request/response handling.
“That utility for reading the request body is an H3 helper, not something Nitro invented on top — worth knowing when you’re searching the docs.”
Build and Output
Nitro build — the compilation step that bundles server code, resolves the target preset, and produces a self-contained output directory ready to deploy.
“The build failed because of a Node-only import leaking into a route meant for the edge preset — check the build output warnings, they usually flag this.”
Prerendering — generating static output for specific routes at build time rather than serving them dynamically at request time.
“That route barely ever changes — prerendering it will cut a full database round-trip on every request in production.”
Storage layer — Nitro’s unified key-value storage abstraction that works consistently across runtimes (filesystem locally, KV or Redis in production) without changing application code.
“Don’t write directly to the filesystem for caching — go through the storage layer, or it’ll silently fail once we’re deployed serverless.”
Common Mistakes
- Saying “the API doesn’t work” without specifying which preset it was deployed with — Node-only code failing on an edge preset is one of the most common Nitro bug reports.
- Treating “server route” and “event handler” as separate concepts in review, when the handler is simply the function that implements the route.
- Forgetting that the storage layer needs a runtime-appropriate driver configured per environment, then being confused why local caching “works” but production caching silently no-ops.
Practice Exercise
- Explain, in two sentences, why the same Nitro route file can run on both Node and an edge runtime without code changes.
- Write a short PR description for migrating a filesystem-based cache to Nitro’s storage layer ahead of an edge deployment.
- Draft a code review comment explaining why a Node-only import should be removed from a runtime-agnostic route handler.