@authhero/admin

The AuthHero admin UI — a Vite + React 19 SPA for managing tenants, users, applications, connections, roles, branding and more across one or many AuthHero deployments.

Built on ra-core (the headless half of react-admin) with shadcn/ui and Tailwind v4.

Quick start

# from the repo root
pnpm install
pnpm admin dev        # starts on http://localhost:5173

# or from this directory
pnpm dev
pnpm build            # production bundle in ./dist
pnpm type-check
pnpm test

Configuration

The admin reads its configuration from two sources, in priority order:

1. Runtime config — window.__AUTHHERO_ADMIN_CONFIG__ (injected by the host page before the bundle loads). Useful when the same static build is served to multiple environments.
2. Build-time env vars — VITE_* variables baked in at pnpm build time.

Both paths share the same keys, defined in src/utils/runtimeConfig.ts.

Settings

Build-time env example

Create apps/admin/.env.local:

VITE_AUTH0_DOMAIN=auth.example.com
VITE_AUTH0_CLIENT_ID=your-spa-client-id
VITE_AUTH0_API_URL=https://auth.example.com
VITE_AUTH0_AUDIENCE=https://auth.example.com/api/v2/
VITE_BASE_PATH=/admin

# Whitelabel
VITE_APP_NAME="Acme Identity Console"
VITE_APP_LOGO_URL=https://cdn.example.com/acme-logo.svg
VITE_APP_FAVICON_URL=https://cdn.example.com/acme-favicon.svg

Runtime config example

Inject before the bundle to swap settings without rebuilding:

<script>
  window.__AUTHHERO_ADMIN_CONFIG__ = {
    domain: "auth.example.com",
    clientId: "your-spa-client-id",
    apiUrl: "https://auth.example.com",
    audience: "https://auth.example.com/api/v2/",
    basePath: "/admin",
    appName: "Acme Identity Console",
    logoUrl: "https://cdn.example.com/acme-logo.svg",
    faviconUrl: "https://cdn.example.com/acme-favicon.svg",
  };
</script>
<script type="module" src="/admin/assets/index-<hash>.js"></script>

The bundle entry filename is fingerprinted by Vite at build time (e.g. index-Ab12Cd.js), so substitute the real filename from your build output — or use window.__AUTHHERO_ADMIN_CONFIG__.basePath to construct it from the configured base path.

If neither source provides a domain, the admin shows a domain picker on first load and stores the choice in a cookie via src/utils/domainUtils.ts.

Whitelabeling

The three branding settings (appName, logoUrl, faviconUrl) are read in three places:

• document.title and the favicon <link> are set on boot by applyBranding() in src/utils/runtimeConfig.ts.
• The top bar in src/components/admin/layout.tsx renders logoUrl as an <img> when set, otherwise the appName wordmark (with two-letter initials as the narrow-width glyph).

To replace the default mark, set VITE_APP_FAVICON_URL to your own asset; the bundled default lives at public/favicon.svg.

Deploying to Cloudflare Pages

The admin is a static SPA, so any static host works. Cloudflare Pages is the recommended target.

In the Cloudflare dashboard, Workers & Pages → Create → Pages → Connect to Git, then:

The trailing ... on the pnpm filter is required — it builds admin's workspace dependencies (notably @authhero/adapter-interfaces) before admin itself. Without it, vite fails to resolve @authhero/adapter-interfaces because the symlinked package has no built dist/.

For SPA client-side routing, add public/_redirects:

/*    /index.html   200

Multiple Cloudflare accounts

Cloudflare's Git integration binds a repo to a single Cloudflare account. To deploy the same codebase to several accounts, you have two options:

1. GitHub Actions + Wrangler — disconnect the Pages Git integration and deploy from CI with cloudflare/wrangler-action, supplying each account's CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as separate GitHub secrets. Build once, deploy N times via a matrix job. Per-account VITE_* values can be set as workflow env at build time, or use the runtime window.__AUTHHERO_ADMIN_CONFIG__ to ship a single artifact.
2. Fork per environment — fork the repo into each Cloudflare account's organisation and connect each fork's Pages project to its own fork. Lower setup cost, at the price of having to merge changes upstream and keep forks in sync.

Architecture notes

• Dual router: the outer router in src/index.tsx handles domain selection (/), tenant management (/tenants/*), per-tenant admin (/:tenantId/*) and the OAuth callback (/auth-callback). The inner router in src/App.tsx is the react-admin router mounted with basename="/:tenantId".
• Auth: @auth0/auth0-spa-js against the configured domain/clientId/audience. The provider lives in src/authProvider.ts.
• Data: a custom data provider in src/auth0DataProvider.ts talks to the AuthHero management API.

See the full docs at authhero.net/apps/admin/.