Nuxt Server Routes: Your Backend in a Folder

Why it exists

To simplify full-stack development by co-locating backend API logic within the same Nuxt project, eliminating the need for a separate server application for many common use cases. This file-based routing system provides a "zero-config" way to create server endpoints.

The mental model

Think of the server/ directory as a mini-backend living inside your Nuxt application. Instead of configuring a router, you just create files. A file named server/api/users.ts automatically becomes an API endpoint available at /api/users. It's convention over configuration for your server logic.

How it works

Nuxt scans the server/ directory for files and maps them to routes. Each file must export a default handler function, typically wrapped in defineEventHandler(). This handler receives an event object and can return JSON data or a Promise. The server/api folder automatically prefixes routes with /api, while the server/routes folder creates routes at the root level (e.g., server/routes/ping.ts becomes /ping). Nuxt also supports dynamic routes using bracket notation (e.g., [id].ts) and server middleware that runs on every request.

When to use it

Use server routes for creating REST APIs for your frontend to consume via useFetch. It's ideal for handling form submissions, fetching data from a database, or integrating with third-party services where you need to hide secret keys. The server/middleware directory is perfect for cross-cutting concerns like request logging or adding authentication context to a request.

When not to use it

For extremely complex or microservice-based architectures, a dedicated standalone backend framework might be more appropriate. While Nuxt's server engine (Nitro) is powerful, server routes are not designed to replace a full-featured backend for large, enterprise-scale applications with specialized needs. Also, avoid putting logic in middleware that should return a response; middleware should only inspect or modify the request, not terminate it.

One canonical example

To create a dynamic user profile endpoint, you would create a file at server/api/users/[id].ts. Inside, you'd define a handler to access the dynamic parameter from the event context: export default defineEventHandler((event) => { const userId = event.context.params.id; return { userId: userId, name: 'Jane Doe' }; }); A useFetch('/api/users/123') call from a component would then return { "userId": "123", "name": "Jane Doe" }.