A Next.js app wants several cross-cutting concerns in middleware — locale detection, a feature-flag cookie, and bot filtering — but a project gets only one middleware file. How do you decide how broad the `config.matcher` should be?

## The constraint that frames everything One project, one middleware module. That single fact removes the design you might reach for first — a per-concern scope, each with its own matcher — and forces a different structure: `config.matcher` is a **union**, and the function is a **dispatcher**. Locale detection, flag reading and bot filtering all live behind the same entry point, and the function itself works out which apply to the request in hand. So the matcher is not "where each feature is configured". It is one decision: which slice of the site's traffic is allowed to reach the dispatcher. ## What that one decision actually controls **Cost.** Every matched request is an invocation on the critical path, before filesystem routes and before prerendered output is served. The population is bigger than page views: asset requests if you have not excluded them, and the RSC payload requests that client navigations and link prefetching issue at real route paths. Breadth here is a multiplier on latency and, on hosts that meter middleware separately, on spend. **Blast radius.** This is the part teams underweight. Middleware is one module in front of everything it matches. A bug, a bad deploy, a slow dependency called inside it, a cold start — the population that suffers is exactly the population the matcher admits. Widening the matcher to cover a concern that only matters on ten routes has quietly made a thousand routes share that code's failure modes. **Coverage.** The mirror risk. Anything outside the matcher does not run the function, and no runtime logic can recover it, because the module was never entered. A narrow matcher is a promise that the path set is stable — and path sets are not stable in apps that people keep adding routes to. ## Sorting the concerns The useful axis is *exhaustiveness*: must this concern hold for every route, including ones that do not exist yet? - **Exhaustive concerns** — locale negotiation that governs URL shape, anything whose absence produces a visibly broken or inconsistent page — want the deny-list shape: a catch-all minus what structurally cannot need it. New routes are covered by default; the cost is that anything you forget to exclude is included. - **Concentrated concerns** — bot filtering on a few expensive endpoints, behaviour tied to one product area — want the allow-list shape. Minimal invocations, bounded blast radius; the cost is silent under-coverage as the app grows. - **Opportunistic concerns** — a feature-flag cookie that a page could equally read where it is used — are the ones to challenge. If a concern does not need to run before route resolution, its presence in middleware is what is forcing the matcher wider, and that is a reason to reconsider rather than to widen. The union of what survives is your matcher. Then subtract the always-safe exclusions — build output, the image optimizer, favicon, static file extensions — because no concern in any category needs those. ## Living with the union Two consequences to accept openly rather than engineer around. First, some matched requests will enter the function and immediately branch to a no-op. That is the price of a union; it is fine as long as the no-op path is genuinely cheap. It is *not* fine if the function does shared setup — a session decode, a config fetch — before branching, because then every matched request pays for a concern that applies to a few. Order the dispatcher so per-concern work happens after the cheap path check. Second, the cost of the broadest concern is paid by everything. If locale detection forces a catch-all, then bot filtering's I/O call now sits in front of the whole site unless the function guards it by path. The dispatcher's internal structure has to reflect the concerns' real scopes even though the matcher cannot. ## Governance, because this decays A matcher regex is written once, reviewed once, and then defines the traffic population of the site's most critical piece of shared code for years. Three habits keep it honest: - **A test over representative paths.** Assert that an asset path, an API path, a marketing path and an authenticated path are or are not matched. This is the cheapest way to stop an edit to one alternation from silently changing what runs. - **A comment per exclusion, and per entry, saying which concern needs it.** When a concern is removed, the entry that existed for it can go too — otherwise breadth only ever ratchets upward. - **A number to watch.** Middleware invocations relative to page views. If that ratio drifts, the matcher has widened or traffic shape has changed, and both are worth knowing before a bill or a latency graph tells you. ## The framing to lead with "There is one middleware, so the matcher is not per-feature configuration — it is a single decision about which traffic shares one piece of code's cost and one piece of code's failure modes. I set breadth from the most exhaustive concern, subtract what can never need it, and then make the resulting population something we test and watch rather than something we wrote down once."