Implementing Custom API Endpoints with Nuxt 3 Nitro

The Problem: Creating Server-Side Logic in Nuxt

When building a Nuxt 3 application, you often need a way to handle server-side logic—such as database queries, secret API key management, or custom data formatting—without exposing that logic to the client browser. The solution is using Nitro, the server engine that powers Nuxt, to create dedicated API routes.

Prerequisites

• Node.js version 14.x or higher.
• An initialized Nuxt 3 project (created via npx nuxi init <project-name>).
• Basic familiarity with TypeScript or JavaScript.

Implementing a JSON API Route

Nuxt 3 uses a file-based routing system for its server directory. Any file placed within server/api/ is automatically mapped to an endpoint under the /api prefix.

1. Create the API Handler

Create a file at server/api/hello.ts. Use the defineEventHandler utility to ensure the function is properly typed and integrated with the Nitro engine.

// server/api/hello.ts
export default defineEventHandler((event) => {
  // Nitro automatically serializes returned objects to JSON
  return {
    message: 'Hello from Nuxt 3 Nitro',
    timestamp: new Date().toISOString()
  };
});

2. Run and Verify in Development

Start the development server from your project root:

npm run dev

Once the terminal displays [nitro] server listening on http://localhost:3000, verify the endpoint using curl or a browser:

# Run this in a separate terminal window
curl -i http://localhost:3000/api/hello

3. Production Build Verification

Development mode uses a different execution path than production. To ensure the endpoint is correctly bundled by Nitro, perform a production test:

1. Stop the dev server (Ctrl+C).
2. Build the application: npm run build.
3. Start the production server: npm run start.
4. Repeat the curl request to verify the response.

Diagnostic Checks

If the endpoint returns a 404 or an error, check the following:

Check	Expected Result	Risk/Common Failure
File Path	server/api/hello.ts	Placing the file in app/api or public/api will result in a 404.
File Extension	.ts or .js	Files with other extensions (e.g., .txt) are ignored by the Nitro scanner.
Handler Export	export default defineEventHandler(...)	Missing the default export prevents Nitro from registering the route.

Limitations and Performance

Nitro handlers run on the server's event loop. Avoid performing heavy synchronous computations or long-running blocking operations (like fs.readFileSync on large files) directly inside the handler. This will block all other incoming requests to your server.

For asynchronous tasks, always use async/await to ensure the event loop remains responsive.

Rollback Procedure

If the new API route causes build failures or conflicts with existing routes:

1. Delete the specific handler file: rm server/api/hello.ts.
2. If the file was committed to version control, revert the change: git checkout HEAD -- server/api/hello.ts.
3. Restart the server process to clear the Nitro cache.