Stacks Middleware

Stacks Middleware

Built into @stacksjs/router. Middleware intercepts requests before they reach route handlers.

Key Paths

• Middleware class: storage/framework/core/router/src/middleware.ts
• Execution engine: storage/framework/core/router/src/stacks-router.ts
• Alias registry: app/Middleware.ts
• Default middleware: storage/framework/defaults/app/Middleware/ (22 files)
• Auth middleware (standalone): storage/framework/core/auth/src/middleware.ts
• Tests: storage/framework/core/router/tests/middleware.test.ts

Middleware Class

import { Middleware } from '@stacksjs/router'

export interface MiddlewareConfig {
  name: string
  priority?: number  // Lower = runs first, default: 10
  handle: (request: EnhancedRequest) => void | Promise<void>
}

export class Middleware {
  readonly name: string
  readonly priority: number
  readonly handle: (request: EnhancedRequest) => void | Promise<void>

  constructor(config: MiddlewareConfig)
}

Creating Custom Middleware

Create a file in app/Middleware/:

// app/Middleware/RateLimit.ts
import { Middleware } from '@stacksjs/router'

export default new Middleware({
  name: 'RateLimit',
  priority: 2,
  async handle(request) {
    // Throw to short-circuit the request
    // throw new HttpError(429, 'Too many requests')

    // Return void to continue to next middleware
  },
})

Short-Circuiting

Middleware can stop request processing by:

1. Throwing an Error with statusCode — converted to HTTP error response
2. Throwing a Response — returned directly to client
3. Returning void — continues to next middleware

// Error with status code
const error = new Error('Unauthorized') as Error & { statusCode: number }
error.statusCode = 401
throw error

// Direct Response (full control)
throw new Response(JSON.stringify({ error: 'Rate limited' }), {
  status: 429,
  headers: { 'Retry-After': '60' },
})

Alias Registry (app/Middleware.ts)

Maps short names to middleware class filenames:

import { defineMiddleware } from '@stacksjs/router'

export default defineMiddleware({
  'maintenance': 'Maintenance',
  'auth': 'Auth',
  'guest': 'Guest',
  'api': 'Api',
  'team': 'Team',
  'site': 'Site',
  'logger': 'Logger',
  'abilities': 'Abilities',
  'can': 'Can',
  'throttle': 'Throttle',
  'signed': 'Signed',
  'env': 'Env',
  'env:local': 'EnvLocal',
  'env:development': 'EnvDevelopment',
  'env:dev': 'EnvDevelopment',
  'env:staging': 'EnvStaging',
  'env:production': 'EnvProduction',
  'env:prod': 'EnvProduction',
  'role': 'Role',
  'permission': 'Permission',
  'verified': 'EnsureEmailIsVerified',
})

The alias is yours to invent; the class name is checked against app/Middleware/ and the framework defaults, so { auth: 'Auht' } is a compile error rather than a route whose guard resolves to nothing.

This map is merged over the framework defaults, not a replacement for them, so an alias Stacks adds later is available without editing the file.

Reference forms

Three shapes are read off a reference, in this order:

The whole reference is looked up as an alias before the colon is treated as a parameter separator. That is what makes 'env:production' its own alias rather than env with a parameter - Env ignores parameters and accepts every known environment, so splitting first turned a production-only route into an unguarded one.

Inversion counts a Response or a status-carrying error as a refusal, and nothing else. A TypeError from a bug inside Auth is a crash, not a declination, and must not let !auth through.

Applying Middleware

Per-Route (Chainable)

route.get('/dashboard', 'DashboardAction')
  .middleware('auth')
  .middleware('verified')
  .name('dashboard.show')

Route Groups

route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
  route.get('/users', listUsers)
  route.post('/users', createUser)
})

STX Pages

The frontend and API share the same middleware definitions. Stacks loads the aliases from app/Middleware.ts and the class-style handlers from app/Middleware/ into the normal stx dev and production page servers.

Declare an alias from that registry in a page's server metadata:

<script server>
definePageMeta({ middleware: ['auth', 'verified', 'role:admin'] })
</script>

Do not create a second frontend-only middleware registry. A custom middleware is defined once with new Middleware({ name, priority, handle }), added to app/Middleware.ts, and may then guard an API route, an stx page, or both.

STX prepares the incoming request with the same EnhancedRequest helpers before calling handle, sorts the combined page chain by priority, writes parameters to request._middlewareParams, supports exact aliases containing colons and !alias inversion, and fails closed when an alias is missing.

Group middleware is prepended to all routes inside the callback. Groups can be nested — middleware accumulates.

Parameterized Middleware

Pass parameters using colon syntax:

route.get('/admin', handler).middleware('throttle:60,1')     // 60 requests per 1 minute
route.get('/posts', handler).middleware('abilities:read,write')
route.get('/settings', handler).middleware('role:admin,editor')
route.get('/posts/{id}', handler).middleware('can:update,post')

Parameters are stored on request._middlewareParams[middlewareName] and parsed by the middleware's handle function.

Default Middleware Reference

Environment Negation Variants

EnvNotLocal, EnvNotDevelopment, EnvNotStaging and EnvNotProduction exist as classes with no alias. Reference them by class name, or write the negated form of the positive alias - '!env:production' is EnvNotProduction.

Middleware Loading Flow

1. Strip a leading '!', if any, and remember it
2. Look the WHOLE remainder up in the merged alias map
   'env:production' is an alias      → { name: 'env:production' }
   'throttle:60,1' is not            → { name: 'throttle', params: '60,1' }
3. Check middleware cache (loaded once, cached for performance)
4. Resolve alias: 'throttle' → 'Throttle'; unaliased names PascalCase
5. Try loading from app/Middleware/Throttle.ts (user overrides)
6. Fall back to storage/framework/defaults/app/Middleware/Throttle.ts
7. Store params on request: request._middlewareParams.throttle = '60,1'
8. Wrap in the inverter if step 1 saw a '!'
9. Sort the chain by priority, then execute: await middleware.handle(req)

User middleware in app/Middleware/ always takes precedence over framework defaults.

Representative Implementations

Auth Middleware

export default new Middleware({
  name: 'Auth',
  priority: 1,
  async handle(request) {
    const bearerToken = request.bearerToken()
    if (!bearerToken)
      throw new HttpError(401, 'Unauthorized. No token provided.')
    const isValid = await Auth.validateToken(bearerToken)
    if (!isValid)
      throw new HttpError(401, 'Unauthorized. Invalid token.')
  },
})

Maintenance Middleware

export default new Middleware({
  name: 'Maintenance',
  priority: 0,
  async handle(request) {
    if (!(await isDownForMaintenance())) return
    const payload = await maintenancePayload()
    // Check secret bypass URL → set cookie and redirect
    // Check bypass cookie or allowed IP → continue
    // Otherwise → throw maintenance response
  },
})

Throttle Middleware (Parameterized)

// '60,1' = 60 requests per 1 minute
// '100,5m' = 100 requests per 5 minutes
// '1000,1h' = 1000 requests per hour
async handle(request) {
  const params = request._middlewareParams?.throttle || '60,1'
  const config = parseThrottleString(params)
  const limiter = createRateLimitMiddleware(config)
  // Returns 429 if rate limit exceeded
}

Standalone Auth Middleware (@stacksjs/auth)

A separate, more complete auth middleware exists:

import { authMiddleware, authMiddlewareHandler } from '@stacksjs/auth'

// Checks both request.bearerToken() and raw Authorization header
// Calls Auth.getUserFromToken() to validate
// Sets Auth.setUser(user) and request._authenticatedUser
// Loads current access token onto request._currentAccessToken

Gotchas

• Priority DOES order the chain — entries are sorted by priority (lower first, default 10) before execution, so CORS can precede auth regardless of the order they were attached in. An earlier version of this file said otherwise. A non-finite or negative value is clamped to the default and warned about once
• terminate() doesn't exist — some docs reference it, but it's not in the actual MiddlewareConfig interface
• Two auth middleware implementations — defaults version (basic token check) and @stacksjs/auth version (full user loading)
• EnvNot files have no aliases* — reachable by class name, or as '!env:production' and friends
• The alias map merges over the defaults — an app's app/Middleware.ts adds to and overrides them rather than replacing the set
• Middleware is cached after first load — changes require server restart
• User overrides take precedence — app/Middleware/Auth.ts replaces the framework default completely
• Group middleware accumulates — nested groups combine all parent middleware
• Request body parsed before middleware — Laravel-style methods (.input(), .query, .file()) are available in middleware