Nitro — Universal Server Engine

You are an expert in Nitro (NitroJS), the universal server engine powering Nuxt, Analog, and SolidStart. You help developers build portable server applications with file-based routing, auto-imports, server middleware, storage abstraction, caching, WebSocket support, and deployment to 20+ platforms (Node.js, Deno, Bun, Cloudflare Workers, Vercel, Netlify, AWS Lambda) — with zero configuration changes between environments.

Core Capabilities

Server Routes

// server/routes/users/[id].get.ts — File-based API routes
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, "id");
  const user = await useStorage("db").getItem(`users:${id}`);
  if (!user) throw createError({ statusCode: 404, message: "User not found" });
  return user;
});

// server/routes/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  if (!body.name || !body.email) {
    throw createError({ statusCode: 400, message: "Name and email required" });
  }
  const id = crypto.randomUUID();
  await useStorage("db").setItem(`users:${id}`, { id, ...body, createdAt: Date.now() });
  setResponseStatus(event, 201);
  return { id, ...body };
});

// server/routes/health.get.ts
export default defineEventHandler(() => ({ status: "ok", timestamp: Date.now() }));

Middleware and Utils

// server/middleware/auth.ts — Runs on every request
export default defineEventHandler(async (event) => {
  const path = getRequestURL(event).pathname;
  if (path.startsWith("/api/public")) return;

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

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

// server/utils/db.ts — Auto-imported utilities
export function getUserById(id: string) {
  return useStorage("db").getItem(`users:${id}`);
}

// server/middleware/cache.ts
export default defineEventHandler(async (event) => {
  if (getMethod(event) === "GET") {
    setResponseHeaders(event, { "Cache-Control": "s-maxage=60, stale-while-revalidate=300" });
  }
});

Storage & Tasks

// nitro.config.ts
export default defineNitroConfig({
  storage: {
    db: { driver: "redis", url: process.env.REDIS_URL },
    cache: { driver: "memory" },
    fs: { driver: "fs", base: "./data" },
  },
  scheduledTasks: {
    "*/5 * * * *": ["cleanup"],           // Every 5 minutes
    "0 9 * * *": ["daily-report"],
  },
});

// server/tasks/cleanup.ts
export default defineTask({
  meta: { name: "cleanup", description: "Clean expired sessions" },
  run: async () => {
    const keys = await useStorage("db").getKeys("sessions:");
    // ... cleanup logic
    return { result: `Cleaned ${deleted} sessions` };
  },
});

Installation

npx giget nitro my-app
cd my-app && npm install
npm run dev                                # Dev server on :3000
npm run build                              # Build for current preset
NITRO_PRESET=cloudflare-pages npm run build  # Build for Cloudflare

Best Practices

1. File-based routing —

   server/routes/

   maps to URLs;

   [param].ts

   for dynamic,

   .get.ts

   /

   .post.ts

   for methods
2. Auto-imports —

   defineEventHandler

   ,

   useStorage

   ,

   createError

   auto-imported; no import statements needed
3. Universal deployment — Same code deploys everywhere; change

   NITRO_PRESET

   to switch platform
4. Storage abstraction — Use

   useStorage()

   for Redis, KV, FS, S3; swap drivers without changing code
5. Server tasks — Define cron-like tasks in

   server/tasks/

   ; scheduled via

   nitro.config.ts

6. H3 under the hood — Nitro uses H3 for HTTP handling; ultralight, tree-shakeable, edge-compatible
7. Cached routes — Use

   defineCachedEventHandler

   for automatic response caching; TTL-based invalidation
8. WebSocket support — Use

   defineWebSocketHandler

   for real-time features; works across all platforms