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