Middleware

A single middleware.ts intercepts every request before routing — ideal for auth, logging, CORS, and custom headers.

Creating middleware

Create middleware.ts at the project root and export a default async function. It receives the raw Node.js IncomingMessage and ServerResponse objects:

middleware.tstypescript

import type { IncomingMessage, ServerResponse } from 'http'

export default async function middleware(
    req: IncomingMessage,
    res: ServerResponse,
): Promise<void> {
    // Inject a response header on every request
    res.setHeader('X-Powered-By', 'nukejs')
    // Return without ending → request continues to routing
}

Halting a request

If middleware calls res.end(), NukeJS stops processing and the request never reaches routing:

middleware.tstypescript

import type { IncomingMessage, ServerResponse } from 'http'
import { verifyToken } from './lib/auth'

export default async function middleware(
    req: IncomingMessage,
    res: ServerResponse,
) {
    res.setHeader('X-Powered-By', 'nukejs')

    // Auth guard for /admin routes
    if (req.url?.startsWith('/admin')) {
        const token = req.headers.authorization?.split(' ')[1]
        const user = await verifyToken(token)

        if (!user) {
            res.statusCode = 401
            res.setHeader('Content-Type', 'application/json')
            res.end(JSON.stringify({ error: 'Unauthorized' }))
            return // ← halts, routing is never reached
        }
    }
    // falls through → normal routing
}

Request logging

middleware.tstypescript

export default async function middleware(req, res) {
    const start = Date.now()

    res.on('finish', () => {
        const ms = Date.now() - start
        console.log(`${req.method} ${req.url} ${res.statusCode} — ${ms}ms`)
    })
}

CORS headers

middleware.tstypescript

export default async function middleware(req, res) {
    res.setHeader('Access-Control-Allow-Origin', '*')
    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS')
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')

    if (req.method === 'OPTIONS') {
        res.statusCode = 204
        res.end()
        return
    }
}

Rate limiting (simple)

middleware.tstypescript

const requests = new Map<string, number[]>()

export default async function middleware(req, res) {
    const ip = req.socket.remoteAddress ?? 'unknown'
    const now = Date.now()
    const window = 60_000 // 1 minute
    const limit = 100

    const hits = (requests.get(ip) ?? []).filter(t => now - t < window)
    hits.push(now)
    requests.set(ip, hits)

    if (hits.length > limit) {
        res.statusCode = 429
        res.end('Too Many Requests')
        return
    }
}

⚠️

One middleware file onlyNukeJS supports a single middleware.ts at the project root. Dispatch to different handlers inside that one file based on req.url.