Overview

Nitro is a universal server engine — write your server code once, deploy it anywhere. Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, AWS Lambda, Netlify — same code, zero config changes. It powers Nuxt's server routes but works standalone for any API or full-stack app. File-based routing, built-in KV storage, auto-imports, and hot reload.

When to Use

Building APIs that need to deploy to multiple platforms
Edge-first applications (Cloudflare Workers, Vercel Edge)
Server-side companion for a frontend framework (not just Nuxt)
Need built-in caching, storage, and task scheduling without external packages
Migrating Express/Fastify to a platform-agnostic solution

Instructions

Setup

bash

npx giget@latest nitro my-server
cd my-server
npm install
npm run dev

File-Based API Routes

server/
├── routes/
│   ├── index.ts            # GET /
│   ├── users/
│   │   ├── index.get.ts    # GET /users
│   │   ├── index.post.ts   # POST /users
│   │   └── [id].get.ts     # GET /users/:id
│   └── health.ts           # GET /health
├── middleware/
│   └── auth.ts             # Runs before every request
├── plugins/
│   └── database.ts         # Initialization logic
└── utils/
    └── db.ts               # Shared utilities (auto-imported)

typescript

// server/routes/users/index.get.ts — List users
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const page = Number(query.page) || 1;
  const limit = Math.min(Number(query.limit) || 20, 100);

  const users = await db.user.findMany({
    skip: (page - 1) * limit,
    take: limit,
  });

  return { users, page, limit };
});

// server/routes/users/index.post.ts — Create user
export default defineEventHandler(async (event) => {
  const body = await readBody(event);

  if (!body.email || !body.name) {
    throw createError({ statusCode: 400, message: "Email and name required" });
  }

  const user = await db.user.create({ data: body });
  setResponseStatus(event, 201);
  return user;
});

// server/routes/users/[id].get.ts — Get user by ID
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, "id");
  const user = await db.user.findUnique({ where: { id } });

  if (!user) {
    throw createError({ statusCode: 404, message: "User not found" });
  }

  return user;
});

Middleware

typescript

// server/middleware/auth.ts — Auth middleware for all routes
export default defineEventHandler(async (event) => {
  // Skip auth for public routes
  const url = getRequestURL(event);
  if (url.pathname === "/health" || url.pathname.startsWith("/auth/")) return;

  const token = getHeader(event, "authorization")?.replace("Bearer ", "");
  if (!token) {
    throw createError({ statusCode: 401, message: "Unauthorized" });
  }

  const user = await verifyToken(token);
  event.context.user = user;
});

Built-in Storage (KV)

typescript

// server/routes/cache/[key].ts — KV storage (works on every platform)
export default defineEventHandler(async (event) => {
  const key = getRouterParam(event, "key")!;

  if (event.method === "GET") {
    const value = await useStorage("cache").getItem(key);
    if (!value) throw createError({ statusCode: 404 });
    return value;
  }

  if (event.method === "PUT") {
    const body = await readBody(event);
    await useStorage("cache").setItem(key, body);
    return { ok: true };
  }
});

Deploy to Any Platform

bash

# Build for different targets
NITRO_PRESET=cloudflare-pages npx nitro build
NITRO_PRESET=vercel npx nitro build
NITRO_PRESET=netlify npx nitro build
NITRO_PRESET=node-server npx nitro build
NITRO_PRESET=deno-server npx nitro build
NITRO_PRESET=bun npx nitro build
NITRO_PRESET=aws-lambda npx nitro build

Examples

Example 1: Build a REST API that deploys to Cloudflare Workers

User prompt: "Create a REST API with CRUD routes that runs on Cloudflare Workers edge."

The agent will create a Nitro project with file-based CRUD routes, middleware for auth, Cloudflare KV for storage, and deploy config for Workers.

Example 2: API with caching and scheduled tasks

User prompt: "Build an API that caches expensive database queries and refreshes them every hour."

The agent will use Nitro's built-in storage for caching, defineTask for scheduled refreshes, and route-level cache headers.

Guidelines

File naming = HTTP method — users.get.ts, users.post.ts, users.delete.ts
[param] for dynamic routes — [id].get.ts captures :id
useStorage() is universal — KV that works on every platform (memory, Redis, Cloudflare KV)
createError() for HTTP errors — structured error responses with status codes
Auto-imports — defineEventHandler, readBody, getQuery are available without imports
Middleware runs on every request — use path checks to skip public routes
NITRO_PRESET for deployment — one codebase, 15+ deployment targets
event.context for request state — pass data between middleware and handlers

nitro

Usage

Getting Started

Example Prompts

Documentation

Overview

When to Use

Instructions

Setup

File-Based API Routes

Middleware

Built-in Storage (KV)

Deploy to Any Platform

Examples

Example 1: Build a REST API that deploys to Cloudflare Workers

Example 2: API with caching and scheduled tasks

Guidelines

Information

Use Cases