Nuxt 3: Architectural Decision Guide for Server-Side Rendering with Nitro

The Problem: SSR Runtime Portability vs. Project Complexity

When building a Nuxt 3 application that requires server-side rendering, you face a fundamental architectural decision: how to structure your server routes and leverage Nitro's cross-platform capabilities without creating maintenance overhead or runtime lock-in.

Requirements Analysis

• Cross-runtime compatibility: Must work locally (Node.js), in CI (Deno/Bun), and in production (serverless, containers)
• API co-location: Server logic should live alongside frontend code, not in separate services
• Minimal configuration: Avoid webpack/Vite config files; rely on Nuxt's conventions
• Security boundary: Server routes must not expose sensitive logic to client bundles

Smallest Suitable Design

Use Nitro's file-based server routes in server/api/ directory. This is the smallest surface area that satisfies all requirements:

project/
├── server/
│   └── api/
│       ├── hello.get.ts      # Maps to /api/hello
│       └── users/
│           └── [id].get.ts   # Maps to /api/users/:id
├── pages/
│   └── index.vue             # Maps to /
└── nuxt.config.ts

Server Route Implementation

Create server/api/hello.get.ts:

export default defineEventHandler((event) => {
  const name = getQuery(event).name || 'world'
  return { message: `Hello ${name}!` }
})

// Test: curl http://localhost:3000/api/hello?name=Nuxt

Trust and Data Boundaries

Nitro enforces a clear separation: server routes run in the server runtime only, while pages/ and components/ are bundled for client consumption. Never place sensitive logic in composables imported by both server and client contexts unless wrapped in process.server checks.

Operational Verification Checks

1. Route discovery: After starting npx nuxi dev, visit http://localhost:3000/api/hello. Expected: JSON response {message: "Hello world!"}
2. Dynamic route parameter: Create server/api/users/[id].get.ts with defineEventHandler((event) => { return { id: event.context.params.id } }). Test: curl http://localhost:3000/api/users/42 returns {"id":"42"}
3. Environment isolation: In server routes, process.env is available. In client components, use useRuntimeConfig().public for safe exposure. Verify: console.log(process.env.NODE_ENV) in server route shows runtime environment

Failure Modes and Diagnostic Paths

Route not found (404): Check directory naming. _id.get.ts is invalid; must be [id].get.ts. Nitro uses brackets for dynamic segments.

Server route executing in browser: If you see process.server errors in client console, verify the file is in server/, not plugins/ or utils/.

Deployment target mismatch: Serverless platforms (Vercel, Netlify) may require nitro.prerender config for static routes. Add to nuxt.config.ts:

export default defineNuxtConfig({
  nitro: {
    preset: 'vercel',
    prerender: {
      routes: ['/']
    }
  }
})

When This Design Changes

• Monorepo with shared API: If multiple Nuxt apps share backend logic, extract server routes to a separate server/ package and configure Nitro's routes option
• Database connection pooling: For high-traffic apps, add server/middleware/ for connection initialization rather than per-request
• Authentication middleware: If route protection is needed, place logic in server/middleware/auth.global.ts, which runs before handler execution

Practical Verification Script

Run these commands to validate your setup:

# Initialize fresh project
npx nuxi init test-nuxt && cd test-nuxt && npm install

# Create test server route
mkdir -p server/api && echo 'export default defineEventHandler(() => ({ ok: true }))' > server/api/health.get.ts

# Start dev server and test
npm run dev &
sleep 5
curl -s http://localhost:3000/api/health | grep -q '"ok":true' && echo "✓ Server route working"

# Kill dev server
kill %1

Limitations

This file-based approach works for most applications, but Nitro's server routes are not standard Express/Fastify. Migration to traditional Node.js frameworks requires rewriting handlers using standard HTTP APIs. Additionally, server routes cannot use Vue component templates—they are pure TypeScript/JavaScript handlers.