@alikhalilll/nuxt-auto-middleware

Map layouts to middlewares once in nuxt.config.ts. The module generates a single global route middleware that dispatches the right chain per navigation. Typed, DRY, zero runtime dependencies.

Live · rule resolution

Install

Register the module and declare your mapping:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@alikhalilll/nuxt-auto-middleware'],
  autoMiddleware: {
    groups: {
      auth: ['auth', 'verify-role'],
    },
    rules: [
      { layouts: ['default'], middlewares: ['log-activity'] },
      { layouts: ['dashboard', 'dashboard/*'], middlewares: ['@auth'] },
      { layouts: ['admin'], middlewares: ['@auth', 'require-admin'] },
    ],
    debug: false,
    pageMetaField: 'middlewares',
  },
});

Middleware files live in the standard Nuxt location: ~/middleware/auth.ts, ~/middleware/verify-role.ts, etc.

Quick start — basic mapping

A single rule, the common case:

autoMiddleware: {
  rules: [
    { layouts: ['default'], middlewares: ['track-pageview'] },
  ],
},

Any page using the default layout runs ~/middleware/track-pageview.ts before rendering. Pages with no explicit layout are treated as default — see matching rules.

Named groups

Groups keep rules DRY when the same stack runs across multiple layouts. Reference a group as @name inside middlewares.

autoMiddleware: {
  groups: {
    auth:      ['auth', 'verify-role'],
    adminOnly: ['auth', 'verify-role', 'require-admin'],
  },
  rules: [
    { layouts: ['dashboard', 'dashboard/*'], middlewares: ['@auth'] },
    { layouts: ['admin', 'admin/*'],         middlewares: ['@adminOnly'] },
  ],
},

Glob patterns

Layouts support * (non-slash), ** (any), and ? (one non-slash char).

rules: [
  { layouts: ['dashboard/*'], middlewares: ['@auth'] },
  { layouts: ['admin/**'],    middlewares: ['@adminOnly'] },
  { layouts: ['settings-?'],  middlewares: ['verify-role'] },
],

RegExp patterns

When globs aren't enough:

rules: [
  { layouts: [/^(dashboard|portal)$/], middlewares: ['@auth'] },
  { layouts: [/^ops\//],               middlewares: ['require-ops'] },
],

Per-page extras

Append middlewares for one page without touching the global rules. The field name (middlewares by default) is configurable via pageMetaField.

<script setup lang="ts">
definePageMeta({
  layout: 'dashboard',
  middlewares: ['force-2fa'],
});
</script>

Opting a page out

<script setup lang="ts">
definePageMeta({
  layout: 'dashboard',
  skipAutoMiddleware: true,
});
</script>

Catch-all layout

Use ** to run a middleware for every layout (except pages with layout: false or skipAutoMiddleware: true):

rules: [
  { layouts: ['**'], middlewares: ['track-pageview'] },
  { layouts: ['dashboard', 'admin'], middlewares: ['@auth'] },
],

When multiple rules match, middlewares are concatenated in config order and deduplicated — first occurrence wins.

Middleware return values

Middleware functions receive (to, from) exactly like standard Nuxt route middlewares.

// ~/middleware/auth.ts
export default defineNuxtRouteMiddleware(() => {
  const token = useCookie('token').value;
  if (!token) return navigateTo('/login');
});

Every middleware runs inside callWithNuxt(), so useNuxtApp() and composables work as usual.

Typed registry

The module emits #build/auto-middleware/types.d.ts:

export type AutoMiddlewareName = 'auth' | 'verify-role' | 'require-admin' | 'log-activity';

Plus an augmentation that adds middlewares?: AutoMiddlewareName[] and skipAutoMiddleware?: boolean to PageMeta.

Matching rules {#matching-rules}

The resolver's rules, in order:

• A page with no explicit layout is treated as default.
• layout: false pages are skipped entirely.
• skipAutoMiddleware: true pages are skipped entirely.
• Layout pattern matching is anchored — partial matches don't count. dashboard/* matches dashboard/overview, not app-dashboard.
• Multiple matching rules are concatenated in config order and deduplicated. First occurrence of a middleware wins.

API reference

Module options

Exported types

import type {
  AutoMiddlewareOptions,
  AutoMiddlewareRule,
} from '@alikhalilll/nuxt-auto-middleware/types';