Blaze Middleware: Built-in Modules and Custom Handlers

Blaze ships 12 tree-shakeable middleware modules using the Express (req, res, next) convention. Any Express middleware works unchanged in Blaze.

Blaze’s middleware system gives you a familiar Express-style (req, res, next) pipeline that runs inside a Cloudflare Worker. Every piece of middleware you’ve written for Express works unchanged in Blaze, and the 12 built-in modules cover the most common API needs — authentication, CORS, caching, rate limiting, and more — without adding a single npm dependency.

How middleware works

When a request arrives, Blaze walks a Layer stack — an ordered array of middleware and route Layers registered at startup. Each Layer has a path (derived from the first argument of app.use()) and a handle function.

• app.use(fn) appends a global Layer that matches every path.
• app.use('/prefix', fn) appends a Layer that only matches paths starting with /prefix.
• Inside each Layer, calling next() hands control to the next matching Layer.
• If a Layer throws synchronously, or an async handler rejects, Blaze catches the error and routes it to the nearest 4-arg error handler.

Middleware registered earlier in your code runs first. Load global concerns — request IDs, loggers, CORS — before route-specific middleware and your route handlers.

import { createApp } from 'blaze'

const app = createApp<Env>()

app.use(requestId())   // ← runs first
app.use(logger())      // ← runs second
app.use('/api', auth)  // ← runs third, only for /api/*

app.get('/api/users', listUsers)

export default { fetch: app.fetch }

When a Layer calls res.json(), res.send(), or res.html(), it resolves the internal response promise and the cycle ends — downstream Layers are not called.

Writing custom middleware

Synchronous middleware

import type { BlazeRequest, BlazeResponse, NextFunction } from 'blaze'

function addRegion(req: BlazeRequest, res: BlazeResponse, next: NextFunction) {
  // req.cf is populated by Cloudflare with datacenter metadata
  res.header('X-Region', req.cf?.region ?? 'unknown')
  next()
}

app.use(addRegion)

Async middleware

async function requirePlan(
  req: BlazeRequest,
  res: BlazeResponse,
  next: NextFunction,
) {
  const plan = await req.env.DB
    .prepare('SELECT plan FROM subscriptions WHERE user_id = ?')
    .bind(req.user?.sub)
    .first<{ plan: string }>()

  if (plan?.plan !== 'pro') {
    return res.status(403).json({ error: 'Pro plan required' })
  }

  next()
}

app.use('/api/export', requirePlan)

Forwarding errors with next(err)

When something goes wrong inside middleware, pass the error to next instead of letting it propagate unhandled. Blaze routes it to the nearest downstream error handler.

async function loadUser(
  req: BlazeRequest,
  res: BlazeResponse,
  next: NextFunction,
) {
  try {
    req.user = await fetchUser(req.env.DB, req.params.id)
    next()
  } catch (err) {
    next(err) // ← forwards to the error handler below
  }
}

Error handlers (4-argument signature)

An error handler is a middleware function that accepts four arguments: (err, req, res, next). Blaze identifies it by arity and only invokes it when an error has been forwarded.

function errorHandler(
  err: unknown,
  req: BlazeRequest,
  res: BlazeResponse,
  next: NextFunction,
) {
  const status = (err as any)?.status ?? 500
  const message = err instanceof Error ? err.message : 'Internal Server Error'

  console.error(`[${req.id}] ${status} ${message}`)
  res.status(status).json({ error: message })
}

// Error handlers must be registered after all other middleware and routes
app.use(errorHandler)

All built-in middleware

cors

Set Access-Control-* headers and handle OPTIONS preflight. Supports dynamic origins, credentials, and maxAge.

import { cors } from 'blaze/middleware/cors'

logger

Log method, path, status, response time, and Cloudflare colo to console.log. Supports short, long, and custom formats.

import { logger } from 'blaze/middleware/logger'

bearerAuth

Validate Authorization: Bearer <token> headers against a static token or an async validator function.

import { bearerAuth } from 'blaze/middleware/bearer-auth'

basicAuth

Decode and verify Authorization: Basic <base64> credentials using timing-safe comparison.

import { basicAuth } from 'blaze/middleware/basic-auth'

jwtAuth

Verify JWTs using Web Crypto (crypto.subtle). Supports HS256 and RS256. Sets decoded payload on req.user.

import { jwtAuth } from 'blaze/middleware/jwt'

rateLimit

Sliding-window rate limiting backed by Cloudflare KV. Configurable per-route with custom key functions.

import { rateLimit } from 'blaze/middleware/rate-limit'

cache

Cache responses via the Cloudflare Cache API. Respects existing Cache-Control headers. Only caches GET by default.

import { cache } from 'blaze/middleware/cache'

compress

Compress response bodies with gzip or deflate via CompressionStream. Checks Accept-Encoding automatically.

import { compress } from 'blaze/middleware/compress'

requestId

Attach a UUID to req.id and echo it as the X-Request-Id response header. Reuses incoming ID if present.

import { requestId } from 'blaze/middleware/request-id'

etag

Generate weak ETags from response bodies using a fast djb2 hash. Handles If-None-Match → 304 automatically.

import { etag } from 'blaze/middleware/etag'

timeout

Race the downstream handler chain against a timer. Calls next(err) with a 408 error if the timer fires first.

import { timeout } from 'blaze/middleware/timeout'

secureHdrs

Set CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy, and CORP/COEP/COOP on every response.

import { secureHdrs } from 'blaze/middleware/secure-headers'

Middleware scope

You control exactly which requests a middleware runs for by where and how you register it.

Global — every request

app.use(requestId())
app.use(logger())
app.use(secureHdrs())

Path-scoped — a URL prefix only

// Only runs for requests to /admin/*
app.use(
  '/admin',
  basicAuth({
    username: (req) => req.env.ADMIN_USER,
    password: (req) => req.env.ADMIN_PASS,
  }),
)

Route-level inline stack

Pass middleware directly as extra arguments to any route method. They run only for that route, in order, before the final handler.

app.post(
  '/upload',
  authenticate,          // ← middleware 1
  validateUploadBody,    // ← middleware 2
  handleUpload,          // ← final handler
)

Sub-router scope

Mount a Router as middleware to apply a shared stack to a group of routes without polluting the global Layer stack.

const api = app.Router()

api.use(jwtAuth({ secret: (req) => req.env.JWT_SECRET }))
api.use(rateLimit({ kvBinding: (req) => req.env.RATE_KV, limit: 100, window: 60 }))

api.get('/users', listUsers)
api.post('/users', createUser)

app.use('/api/v1', api)