How to register a middleware for a specific route?

[gjfLeo]

In the document, it says:

Middleware in server/middleware/ directory are automatically registered for all routes. If you want to register a middleware for a specific route, see Object Syntax Event Handler.

But I have no idea how to use that. Is there any example? Like a middleware for "/images/:fileId"?

[itsSilver]

i dont think you can do that with the current nitro version. one way that i handeled that was to get getRequestURL and skip the middleware for certain routes:

export default defineEventHandler(async (event) => {
  // Skip middleware for certain routes 
  const url = getRequestURL(event)
  const skipRoutes = [
    '/api/public',
    '/api/auth',
    // Add other routes that don't need to be run
  ]

  // Check if current route should skip clinic context
  const shouldSkip = skipRoutes.some(route => url.pathname.startsWith(route))
  if (shouldSkip) {
    return
  }

  // Only run on API routes or specific paths
  if (!url.pathname.startsWith('/api/')) {
    return
  }

  try {
    // your logic here
  }
  catch (error: any) {
    // Handle errors appropriately
    if (error.statusCode) {
      throw error
    }

    throw createError({
      statusCode: 500,
      statusMessage: 'Failed to load clinic context',
    })
  }
})

[aymenhmaidiwastaken]

Nitro's server/middleware/ directory registers middleware for all routes — there's no file-based way to scope it to a specific path.

The docs reference h3's Object Syntax, which lets you attach middleware to a specific handler. Here's how:

Option 1 — Route-level middleware using Object Syntax:

In your route handler file (e.g., server/routes/images/[fileId].get.ts):

import { defineEventHandler } from 'h3';

const myMiddleware = defineEventHandler((event) => {
  // this runs before the main handler
  // e.g., auth check, logging, etc.
  console.log('middleware for /images route');
});

export default defineEventHandler({
  onRequest: [myMiddleware],
  handler: async (event) => {
    const fileId = getRouterParam(event, 'fileId');
    // your actual handler logic
    return { fileId };
  },
});

Option 2 — Global middleware with path filtering:

// server/middleware/images-auth.ts
export default defineEventHandler((event) => {
  const url = getRequestURL(event);
  if (!url.pathname.startsWith('/images/')) return;

  // your middleware logic only for /images/*
});

Option 1 is cleaner when you want middleware tied to a specific route. Option 2 works when you need to cover a group of routes with a prefix pattern.

The key h3 feature is the onRequest array in the object syntax — it acts as route-scoped middleware that runs before the handler.