Nuxt 3: Choosing Between Server Middleware and Plugins for Request Logic

The Decision: Server-Side Logic vs. App Initialization

When building a Nuxt 3 application, you often need to execute logic before a page reaches the user. The challenge is deciding where that logic belongs: in server/middleware or in a Nuxt plugin. Choosing the wrong one can lead to security holes—such as bypassing authentication during client-side navigation—or bloated client-side bundles.

The core distinction is execution timing. Server middleware intercepts the raw HTTP request before it ever hits the Nuxt rendering engine. Plugins, conversely, initialize the Vue application instance and provide global functionality to your components.

Comparison of Execution Models

Feature	Server Middleware	Nuxt Plugins
Execution Frequency	Every single server request	Once during app bootstrap
Environment	Node.js / Nitro server only	Server (SSR) and Client (Hydration)
Primary Use Case	Auth checks, logging, API proxying	Global composables, 3rd party SDKs
Access to Vue	No (Raw Request/Response)	Yes (NuxtApp instance)

Evaluating the Trade-offs

When to use Server Middleware

Use server middleware when you need to modify the response before the Vue app is even considered. This is critical for security headers or authentication redirects. Because it runs in the Nitro server layer, it has a lower overhead for simple checks and can terminate a request (e.g., returning a 401 Unauthorized) without wasting resources on rendering a page.

Critical Limitation: Server middleware is invisible to the client. If a user navigates from /home to /dashboard via a <NuxtLink>, the browser performs a client-side transition. The request never hits the Nitro server, meaning your server middleware is bypassed. You must pair server middleware with client-side route guards for full security.

When to use Plugins

Plugins are the correct choice when you need to "inject" functionality into the Vue app. If you need a global helper available via useNuxtApp() or need to configure a library like Vue-I18n or a tracking pixel that must persist across page changes, a plugin is required.

Critical Limitation: Plugins that run on the client increase your JavaScript bundle size. Logic placed here that is only needed for the initial request should be moved to the server layer to improve Time to Interactive (TTI).

Implementation: Request-Based Authentication Middleware

This example demonstrates a server middleware that checks for an API key in the request headers. This is run on the server (Node.js) and requires Nuxt 3.10+ for the automatic directory scanning feature.

1. Create the Middleware File

Create a file at server/middleware/auth.ts. Files in this directory are automatically registered by Nitro.

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  // Extract the authorization header from the H3 event
  const authHeader = getHeader(event, 'authorization')

  // Example: Simple check for a static token
  // In production, validate this against a database or JWT secret
  if (authHeader !== 'Bearer secret-token-123') {
    // throwCreateError is an H3 utility to return a specific HTTP status
    throw createError({
      statusCode: 401,
      statusMessage: 'Unauthorized: Invalid or missing API key',
    })
  }
})

2. Verification and Testing

To verify the middleware is active, run nuxt dev and attempt to access your site using a tool like cURL or Postman:

• Test Failure: Run curl -I http://localhost:3000. You should receive a 401 Unauthorized response.
• Test Success: Run curl -I -H "Authorization: Bearer secret-token-123" http://localhost:3000. You should receive a 200 OK response.

3. Rollback and Removal

Since this implementation uses the server/middleware/ directory, there is no configuration in nuxt.config.ts to revert. To disable this logic, simply delete the auth.ts file or rename it to auth.ts.bak to prevent Nitro from loading it during the next build/restart.

Diagnostic Decision Summary

If you are unsure which to use, ask: "Does this logic need to access the Vue component tree or the NuxtApp instance?"

• Yes: Use a Plugin.
• No, it only needs the HTTP request/response: Use Server Middleware.