Each route declares its access rule once, and everything that gates on it reads that one declaration.

The problem

A common bug: someone hides a nav link behind a feature flag, but the route never checks the flag, so anyone with the URL walks right in. Or the route is locked and the link still shows, dropping people on an error.

Two copies of the same rule will drift. And a third copy usually lives in the test setup, faking access in its own way.

What I concluded

Access is data. Each route declares what it needs, across three dimensions: a feature flag, a plan feature and a permission. One function checks a session against that declaration and returns the first thing that fails, or nothing.

export const reportsAccess: Access = {
  flag: "reports-v2",
  planFeature: "reports",
  anyOf: [{ action: "READ", area: "reports" }],
};

createFileRoute("/reports")({
  beforeLoad: ({ context }) =>
    requireAccess(context.session, reportsAccess),
});

The route’s guard throws if the check fails. The nav item points at the same object and filters itself out. A useCan hook lets a button ask the same question. Change the declaration and all of them move together.

The order picks the honest error

Flag first, then plan, then permission. Each failure is a typed error that carries its data, and each renders a different page inside the app shell, so the nav stays put:

  • Flag off renders “not found”. The feature is unreleased. Saying “this is behind a flag” would announce it to everyone outside the rollout.
  • Not in plan is a sales moment. Name the feature, say which plan has it, and offer the action this person can take: upgrade, or ask an admin.
  • Permission denied is the only one that reads like an error, and it says who to ask.

One session, loaded once

The root route loads flags, plan and permissions together into one session before any child guard runs, so every guard is a plain synchronous check. Test stories mock that same session, full admin by default, and each story overrides only the dimension it’s testing. The real guard then renders the real upsell or the toolbar with the button gone.

Rules

  • Declare once, derive everywhere. Route, nav and controls read one object.
  • Visibility is computed. No hand-written “show this link” flags.
  • Errors render inside the shell, never on a blank page with nowhere to go.
  • Disable with a reason rather than hide, when the control matters. Keep it focusable and say why.
  • The client gate is UX, not security. The server enforces every real permission.

What you get

There’s nothing to keep in sync. The link, the page and the button agree because they read the same rule, and stories test the real gates instead of a mock-only auth system.

Related: Typed routes, Overrides, Data access.