Reusing authentication/permission across routes

[dorshinar]

Hi!
I was looking at docs about creating RBAC based routes, and I see that permission scopes are defined in multiple places rather than shared.

Example scenario - <Admin /> page that requires write:admin scope. The check happens in the beforeLoad of the route.
I have another route, not a child of <Admin />, open to all users that shown a list of links. For admins I want to show the link to the admin panel based on whether they have the write:admin scope.

I don't want to inline the scope in both checks as that may cause a drift in the future. What is the best way to share this scope information?

[mg1986jp]

Define your route permissions in a single shared object, then reference it from both the route's beforeLoad and wherever you render conditional UI.

// src/permissions.ts
export const routePermissions = {
  admin: ["write:admin"],
  billing: ["read:billing", "write:billing"],
  // ...
} as const;

In your route:

// src/routes/admin.tsx
import { routePermissions } from "../permissions";

export const Route = createFileRoute("/admin")({
  beforeLoad: ({ context }) => {
    const missing = routePermissions.admin.filter(
      (p) => !context.auth.scopes.includes(p)
    );
    if (missing.length) throw redirect({ to: "/unauthorized" });
  },
});

In your links page:

import { routePermissions } from "../permissions";

function NavLinks() {
  const { scopes } = useAuth();
  const hasAdmin = routePermissions.admin.every((p) => scopes.includes(p));

  return (
    <nav>
      {hasAdmin && <Link to="/admin">Admin Panel</Link>}
    </nav>
  );
}

The key is that routePermissions is the single source of truth. If admin ever needs an additional scope, you change it in one place.

If you want to go further, you could write a small helper that takes a permissions key and returns both a beforeLoad guard and a hasAccess check function — but honestly for most apps the shared object is enough.

[DaCameraGirl]

Here's a complete, wired-up implementation using TanStack Router's router context — this is the cleanest pattern for exactly your use case.

Step 1: Define permissions as a single source of truth

// src/lib/permissions.ts
export const permissions = {
  admin: ['write:admin'] as const,
  billing: ['read:billing', 'write:billing'] as const,
} as const;

export type PermissionScope = (typeof permissions)[keyof typeof permissions][number];

export function hasScope(userScopes: string[], required: readonly string[]): boolean {
  return required.every((scope) => userScopes.includes(scope));
}

Step 2: Put user scopes in the router context

// src/router.ts
import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

export interface RouterContext {
  auth: {
    user: User | null;
    scopes: string[];
    isAuthenticated: boolean;
  };
}

export const router = createRouter({
  routeTree,
  context: {
    auth: { user: null, scopes: [], isAuthenticated: false }, // populated at app boot
  },
});

Step 3: Protect routes with beforeLoad

// src/routes/_admin.tsx (layout route for admin section)
import { createFileRoute, redirect } from '@tanstack/react-router';
import { permissions, hasScope } from '@/lib/permissions';

export const Route = createFileRoute('/_admin')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login' });
    }
    if (!hasScope(context.auth.scopes, permissions.admin)) {
      throw redirect({ to: '/unauthorized' });
    }
  },
});

Step 4: Reuse the same check in conditional UI — no duplication

// src/routes/index.tsx (the route that shows the admin link)
import { useRouterState } from '@tanstack/react-router';
import { permissions, hasScope } from '@/lib/permissions';

function NavLinks() {
  // Get scopes from router context — same source as beforeLoad
  const { auth } = useRouterState({ select: (s) => s.options.context });

  const isAdmin = hasScope(auth.scopes, permissions.admin);

  return (
    <nav>
      <Link to="/">Home</Link>
      {isAdmin && <Link to="/admin">Admin Panel</Link>}
    </nav>
  );
}

Why this avoids drift

• permissions.admin is the single definition — if write:admin changes to manage:admin, you change it in one place
• hasScope is the single evaluation function — the logic for "does this user have access" is identical in both beforeLoad and conditional UI
• The router context (context.auth.scopes) is the single data source — both route guards and UI components read from the same object

Bonus: Generic createRouteGuard helper

If you have many permission-gated routes, a factory keeps things DRY:

import { redirect } from '@tanstack/react-router';
import { hasScope, type PermissionScope } from '@/lib/permissions';

export function requireScopes(required: readonly PermissionScope[]) {
  return ({ context }: { context: RouterContext }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login' });
    }
    if (!hasScope(context.auth.scopes, required)) {
      throw redirect({ to: '/unauthorized' });
    }
  };
}

// Usage:
export const Route = createFileRoute('/_admin')({
  beforeLoad: requireScopes(permissions.admin),
});