Middleware is common in frameworks like Nuxt because it reduces repetitive code.

At first glance, this seems helpful.

Often, it is helpful.

But server middleware creates hidden complexity, obscuring what's actually happening in your routes.

Let me show you why server middleware (and not route middleware) is an anti-pattern, and what you should be doing instead.

Server Middleware Looks Convenient

Middleware initially looks convenient because it lets you write repetitive logic only once. You might create global middleware for authentication, feature flags, or setting headers.

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  const token = getHeader(event, 'Authorization');
  if (!validateToken(token)) {
    throw createError({ statusCode: 401, message: 'Unauthorized' });
  }
  event.context.user = getUserFromToken(token);
});

// server/api/user.ts
export default defineEventHandler((event) => {
  const user = event.context.user;
  return { user };
});

However, this convenience can quickly turn into confusion, because server middleware (aka Nitro middleware) are global, and run on every single route.

This causes two main issues:

1. It hides logic flow in your app
2. It makes your routes slower by increasing the bundle size

Hiding Logic Flow

Middleware in general can hide the flow of your logic, making it hard to trace or debug.

Sometimes, this is okay, and exactly what we want. We want that logic to be abstracted away so we don’t have to think about it all.

But because server middleware is global, it can become a big mess. Route middleware doesn’t have this same issue because we can specify exactly which routes run the middleware, as well as being able to specify that middleware in the page itself.

<script setup>
definePageMeta({
  middleware: ['auth', 'is-admin']
});
</script>

Understanding what's happening in each route means tracking down global logic in multiple middleware files. This slows down debugging and makes your application harder to understand.

Your Routes are Slower

The second issue is performance.

Nitro uses code-splitting, which means that when your Nuxt app is built, each route is compiled as a separate “app” that can be run entirely on it’s own. This makes it super fast, because during a request only the necessary code is loaded and run, not the entire app.

Nuxt App
│
├─ /api/user              (small bundle)
├─ /api/user/:id          (small bundle)
├─ /api/user/:id/settings (small bundle)
└─ /api/...               (small bundle)

But since server middleware runs globally, every request must also load and execute the middleware code, even when it’s completely unnecessary. This inflates your server bundle size and makes your routes slower.

Explicit Utility Checks Are Better

An alternative is to explicitly call small utility methods at the top of your server routes.

This method is common in frameworks like Ruby on Rails, where controllers use explicit before_action methods to handle logic clearly:

class PostsController < ApplicationController
  before_action :authenticate_user
  before_action :check_feature_flag

  def index
    @posts = Post.all
    render json: @posts
  end
end

This Ruby controller explicitly runs authentication and feature flag checks before executing the index action. This clearly states what logic applies to this specific route.

In Nuxt, you can do something similar with Nitro’s utility methods.

First, create your util method in server/utils/:

// server/utils/auth.ts
export function requireAuth(event: H3Event) {
  const token = getHeader(event, 'Authorization');
  if (!validateToken(token)) {
    throw createError({ statusCode: 401, message: 'Unauthorized' });
  }
  event.context.user = getUserFromToken(token);
}

Then call it in your route:

// server/api/posts.ts
export default defineEventHandler((event) => {
  requireAuth(event);

  const posts = fetchPostsForUser(event.context.user);

  return { posts };
});

Now it's clear exactly what's happening and what logic applies to this specific route. You also get the added benefit of more control, since you can pass in arguments to the requireAuth method (or whatever util method you have).

When Server Middleware Still Makes Sense

Server middleware is still useful for logic that genuinely needs to run everywhere, such as logging requests or handling headers universally:

// server/middleware/logger.ts
export default defineEventHandler(async (event) => {
  const storage = useStorage('telemetry');
  await storage.setItem(`request:${Date.now()}`, {
    url: getRequestURL(event),
    method: event.method,
    headers: getRequestHeaders(event),
  });
});

This middleware logs basic telemetry data (URL, method, headers) for each incoming request into Nuxt's built-in storage (unstorage).

But for anything route-specific or conditional, explicit utility methods are clearer and more efficient.

Conclusion

Middleware isn't always wrong, but it's usually not the best choice for clarity and maintainability.

Explicitly importing utility functions into each route makes your application's logic clearer and easier to maintain.