Route rules are implemented outside of h3 — by Nitro, and now by h3-rules. The behaviour lives outside core, but the type describing it currently has no canonical home: it is declared by whichever package implements the rules.

That means the module you augment depends on which package you happen to depend on. Nitro apps today augment h3-rules, and previously NitroRouteRules. If another module wants to read or contribute a rule, it has to pick one of those packages and take on a dependency for a type alone.

This PR moves the declaration to the one package everyone in the chain already depends on.

What's added

An empty RouteRules interface, exported from h3, as the canonical extension point:

declare module "h3" {
  interface RouteRules {
    swr?: number | boolean;
    redirect?: string | { to: string; status?: number };
  }
}

h3 itself declares no rules and implements no behaviour — it only owns the name, so that every module merges into the same interface.

Matched rules are also typed where rule modules already put them:

export interface H3EventContext {
  routeRules?: Readonly<RouteRules>;
}

Nitro's generated middleware already assigns event.context.routeRules, so this types a field that exists today rather than introducing one.

Notes

The interface is closed until augmented. With no augmentation, event.context.routeRules?.swr is a compile error rather than unknown — so typos in rule names are caught. Modules that want open-ended keys can add an index signature via augmentation.

Rules are exposed as Readonly. Rule matchers are commonly memoized (Nitro's is), so a single matched object can be shared across requests and mutating it in place would leak between them. Readonly is applied at the consumption site rather than asked of each augmenter, so existing augmentations get it for free and a future one can't forget it. Replacing the whole object still works, so how rule modules attach rules is unaffected. Note this is shallow: nested rule objects are not deeply frozen by the type.

For rule modules

Augmentations keep merging through h3's re-export, so h3-rules can re-export h3's interface and Nitro's existing declare module "h3-rules" augmentation continues to reach it — NitroRouteRules needs no change.

Test plan

• Type tests in test/unit/types.test-d.ts cover that an augmentation merges into the interface used by event.context, that undeclared keys stay an error, that matched rules are readonly, and that whole-object assignment still compiles.
• Verified against the built dist/ types that a downstream declare module "h3" resolves through the entry re-exports, so the extension point works for real consumers and not just in-repo.
• pnpm lint and the full suite pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for defining and extending route rules with TypeScript.
  • Matched route rules are now available through the request context for route handlers.
  • Route rule values are exposed as read-only, helping prevent accidental changes during request handling.
• Documentation
  • Added guidance for extending route rule types with custom application-specific settings.
• Tests
  • Added type checks covering custom rules, read-only behavior, and invalid rule access.