@netlify/redirect-matcher

Netlify's redirect rule matcher, compiled to WebAssembly, for matching requests against Netlify redirect rules in local tooling.

import { createMatcher } from '@netlify/redirect-matcher'

const matcher = await createMatcher(rules, { jwtSecret, jwtRoleClaim })
const result = matcher.match({ scheme: 'https', host, path, query, headers, cookies })

if (result?.type === 'match') {
  console.log(result.status, result.to)
}

matcher.close()

rules is the JSON produced by @netlify/redirect-parser, as a string or an array. Rules that fail to parse are skipped and listed in matcher.parseErrors. match returns null when nothing matched, and { type: 'forcedNotFound' } when a role-gated rule rejected the request and no later rule matched.

headers and cookies may be plain objects or iterables of [name, value] pairs, such as Headers or Map. Header names are matched case-insensitively, so names that differ only in case collide, and the last one wins. A header whose value is an array matches on its first element, and null or undefined values are treated as absent.

Loading the matcher defines these globals, which Go's WebAssembly runtime needs: globalThis.Go, globalThis.__netlifyRedirectMatcher, and, if they are not already defined, stub globalThis.fs and globalThis.path objects.

Requires Node.js 22.12 or later.