Features

Authentication

Web authentication architecture using Supabase and @kit/auth.

What It Does

Authentication in web apps is configured by auth.config.ts, enforced in proxy, and rendered through @kit/auth pages/components.

When To Use

Initial auth setup in a new app.
Changing auth providers or auth UX.

Prerequisites

Supabase project auth providers configured.
apps/<app>/config/auth.config.ts present.

Important

This page describes the standard kit integration path; adapt app-specific paths and config names when your project differs.

How To Use

Auth config

apps/dashboard/config/auth.config.ts


import { parseAuthConfig } from '@kit/auth/config';
import { dashboardRoutes, marketingRoutes } from '@kit/shared/config/routes';
 
export const authConfig = parseAuthConfig({
  environment: 'www',
  scopePatterns: {
    auth: '/auth/*?',
    private: '/(dashboard|onboarding)/*?',
  },
  urls: {
    exit: marketingRoutes.url,
    dashboard: dashboardRoutes.paths.dashboard.index,
    callback: dashboardRoutes.paths.auth.callback,
    signIn: dashboardRoutes.paths.auth.signIn,
    signUp: dashboardRoutes.paths.auth.signUp,
    forgottenPassword: dashboardRoutes.paths.auth.forgottenPassword,
    verifyMfa: dashboardRoutes.paths.auth.verifyMfa,
    contactPage: marketingRoutes.url + marketingRoutes.paths.lang.contact,
    privacyPolicy: marketingRoutes.url + marketingRoutes.paths.lang.privacyPolicy,
    termsOfUse: marketingRoutes.url + marketingRoutes.paths.lang.termsOfUse,
  },
  providers: {
    password: true,
    oAuth: ['google'],
  },
});

Auth pages and callback

app/auth/[path]/page.tsx uses AuthPages + getWithAuthConfig.
app/auth/callback/route.ts handles provider callback.

Auth email webhook

app/api/auth-email-webhook/route.ts:

import { createAuthEmailWebhookHandler } from '@kit/auth/www/routes/auth-email-webhook';
import { appConfig } from '~/config/app.config';
 
export const POST = createAuthEmailWebhookHandler(appConfig);

Filter API

Authentication composes redirect behavior and package translations through filters instead of app-specific hardcoding.

Filter	Parameters	Return	Registered By (package file)	Initialized In (app entrypoint)	Environment
`auth_on_sign_in_redirect_url`	`{}`	`string`	`kit/organization/src/www/filters/use-filters/use-auth-filters.tsx`	`apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`)	`client`
`auth_on_sign_up_redirect_url`	`{}`	`string`	`kit/organization/src/www/filters/use-filters/use-auth-filters.tsx`	`apps/dashboard/hooks/use-filters.ts` (`useOrgFilters`)	`client`
`cross_env_get_translations`	`{ language: string; namespace: string }`	`Record<string, string> \| null`	`kit/auth/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`
`cross_env_get_namespaces`	`{}`	`string[]`	`kit/auth/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`

Init Checklist

Register auth package cross-env filters in apps/dashboard/lib/init-cross-env-filters.ts.
Mount org auth filters via useOrgFilters({ orgConfig }) in apps/dashboard/hooks/use-filters.ts.

MCP Context


capability: auth_web_setup
entrypoints:
  - apps/dashboard/config/auth.config.ts
  - apps/dashboard/app/auth/[path]/page.tsx
  - apps/dashboard/app/api/auth-email-webhook/route.ts
  - kit/auth/src/config.ts
  - kit/auth/src/www/filters/cross-env-filters.ts
  - kit/organization/src/www/filters/use-filters/use-auth-filters.tsx
  - apps/dashboard/lib/init-cross-env-filters.ts
  - apps/dashboard/hooks/use-filters.ts
inputs:
  - auth_providers
  - urls_and_scope_patterns
outputs:
  - sign_in_sign_up_and_callback_flow
constraints:
  - provider setup must also be enabled in Supabase project
side_effects:
  - manages user sessions and auth state transitions

Agent Recipe

Configure authConfig first.
Wire auth pages/callback route.
Add auth email webhook route for branded auth emails.

Troubleshooting

Callback loops usually mean incorrect callback URL in config or Supabase redirect settings.
Missing provider buttons usually means provider not enabled in both config and Supabase.

Metrics Card

A composable metrics card component for displaying analytics data with charts, values, and trends.

Integration

Step-by-step auth integration for an existing web app.

How is this guide?

Last updated on 3/27/2026