alien-middleware

Reusable Web middleware chains need clear boundaries: this page names the core pieces, when to use each entrypoint, and where to go for implementation details.

alien-middleware builds immutable middleware chains around Web Request and Response objects. Middleware can end the request by returning a Response, extend the downstream context by returning a request plugin, or keep the chain moving by returning nothing.

The package is designed for fetch-compatible servers. Use the root entrypoint for portable Web request handling, alien-middleware/srvx when mounting in srvx, and alien-middleware/router when path and method matching belongs in the chain.

First Decisions

Decision	Use	Start here
Build a first chain	chain() plus .use()	Getting Started
Add auth, logging, headers, or context data	Request middleware and response callbacks	Writing Middleware
Build a larger application stack	Common chains, feature middleware, and lazy context resources	Middleware Stacks
Serve through srvx	toFetchHandler from alien-middleware/srvx	Using srvx
Use Rouzer as an alien-middleware provider	Rouzer exports such as chain and toFetchHandler	Rouzer Integration
Match paths and HTTP methods	routes() from alien-middleware/router	Routing Requests
Understand context, env, host, and lifecycle hooks	RequestContext and RequestHost	Request Context
Keep inference strong across chains	chain generics and exported utility types	Type Inference
Look up package entrypoints	public export map and generated declarations	Public API
Fix a symptom	known runtime and type problems	Troubleshooting
Upgrade from v0.11	Hattip-to-srvx migration steps	Migrating from v0.11 to v0.12

Minimal Chain

Create a chain when several request steps should share one typed context:

import { chain } from 'alien-middleware'

const app = chain()
  .use(context => {
    context.setHeader('X-Powered-By', 'alien-middleware')
  })
  .use(context => {
    return new Response(`Hello from ${context.url.pathname}`)
  })

Calling app with an alien-middleware context resolves to a Response. When no middleware returns a response, the final handler returns 404 Not Found.

import { createContext } from 'alien-middleware'

const response = await app(
  createContext({
    request: new Request('http://localhost/hello'),
  })
)

console.log(response.status)

Package Shape

Entrypoint	Main exports	Use when
alien-middleware	chain, MiddlewareChain, createContext, toFetchHandler, filterRuntime, core types	You want host-agnostic Web middleware.
alien-middleware/srvx	toFetchHandler, createContextFromServerRequest, srvx context types	You serve with srvx and want ServerRequest metadata copied into context.host.
alien-middleware/router	routes, router and route types	You need path params and method filtering inside a middleware chain.

Somewhere, E.T. is nodding at the fetch handler and whispering "home route."