DEV Community: Gaurav Guha

Wire Supabase Auth and Database into Next.js App Router

Gaurav Guha — Sun, 01 Nov 2026 13:31:51 +0000

The Problem

Wiring Supabase into a Next.js App Router project looks simple until server components return stale sessions, middleware breaks auth refresh, or row-level security gets skipped entirely. This guide covers the full integration with the gotchas that actually bite.

Create the Supabase Project

Sign up at supabase.com and create a project in a region near your users. The free tier gives 500 MB database, 1 GB storage, 2 GB egress, and 50,000 monthly active auth users.

From the API settings grab three values:

SUPABASE_URL: the project's API endpoint
SUPABASE_ANON_KEY: public client-side key (safe to ship)
SUPABASE_SERVICE_ROLE_KEY: server-side admin key (never expose to the browser)

Install SDK and Configure Environment

npm install @supabase/supabase-js @supabase/ssr

Add to .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...your-anon-key
SUPABASE_SERVICE_ROLE_KEY=eyJ...your-service-role-key

The NEXT_PUBLIC_* prefix exposes variables to the browser. The service role key has no prefix because it must stay server-side.

Create Three Supabase Clients

Next.js 16 with the App Router needs a server client, a browser client, and a middleware client.

lib/supabase/server.ts:

import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function createClient() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll: (cookiesToSet) => {
          cookiesToSet.forEach(({ name, value, options }) => {
            cookieStore.set(name, value, options);
          });
        },
      },
    }
  );
}

lib/supabase/client.ts:

import { createBrowserClient } from '@supabase/ssr';

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

middleware.ts at project root:

import { createServerClient } from '@supabase/ssr';
import { NextResponse, type NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request });
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => request.cookies.getAll(),
        setAll: (cookiesToSet) => {
          cookiesToSet.forEach(({ name, value, options }) => {
            response.cookies.set(name, value, options);
          });
        },
      },
    }
  );
  await supabase.auth.getUser();
  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

The middleware refreshes the auth session on every request. Without it, server components see stale sessions.

Wire Auth Into the Template

Replace template auth handlers with Supabase calls.

'use server';
import { createClient } from '@/lib/supabase/server';
import { redirect } from 'next/navigation';

export async function login(formData: FormData) {
  const supabase = await createClient();
  const { error } = await supabase.auth.signInWithPassword({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });
  if (error) return { error: error.message };
  redirect('/dashboard');
}

Signup handler:

export async function signup(formData: FormData) {
  const supabase = await createClient();
  const { error } = await supabase.auth.signUp({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
    options: { emailRedirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback` },
  });
  if (error) return { error: error.message };
  redirect('/auth/check-email');
}

OAuth (Google example):

export async function signInWithGoogle() {
  const supabase = await createClient();
  const { data } = await supabase.auth.signInWithOAuth({
    provider: 'google',
    options: { redirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback` },
  });
  if (data.url) redirect(data.url);
}

Callback route at app/auth/callback/route.ts:

import { createClient } from '@/lib/supabase/server';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url);
  const code = searchParams.get('code');
  if (code) {
    const supabase = await createClient();
    await supabase.auth.exchangeCodeForSession(code);
  }
  return NextResponse.redirect(`${origin}/dashboard`);
}

Enable OAuth providers in the Supabase dashboard under Authentication > Providers.

Query Database from Server Components

Server components run on the server, so database calls happen inside the Vercel function: no API route needed for read-only views.

import { createClient } from '@/lib/supabase/server';

export default async function ProjectsPage() {
  const supabase = await createClient();
  const { data: projects, error } = await supabase
    .from('projects')
    .select('*, tasks(count)')
    .order('created_at', { ascending: false });

  if (error) throw new Error(error.message);

  return (
    <div>
      {projects.map((p) => (
        <div key={p.id}>{p.name}</div>
      ))}
    </div>
  );
}

Enable Row-Level Security

This is the step most teams skip. Without RLS, your anon key gives the browser unrestricted access to every table.

For a projects table where each project belongs to a user:

-- Enable RLS on the table
alter table projects enable row level security;

-- Allow users to select only their own projects
create policy "Users can view their own projects"
  on projects for select
  using ( auth.uid() = user_id );

-- Allow users to insert projects with their own user_id
create policy "Users can insert their own projects"
  on projects for insert
  with check ( auth.uid() = user_id );

-- Allow users to update their own projects
create policy "Users can update their own projects"
  on projects for update
  using ( auth.uid() = user_id );

-- Allow users to delete their own projects
create policy "Users can delete their own projects"
  on projects for delete
  using ( auth.uid() = user_id );

Run this in the Supabase SQL editor for every table with user-specific data. Test by hitting the API with the anon key from a logged-out browser tab: every query should return empty.

File Uploads via Supabase Storage

Create a storage bucket in the dashboard. Set to "private" for user-uploaded files (avatars, attachments).

Upload from a client component:

'use client';
import { createClient } from '@/lib/supabase/client';

async function uploadAvatar(file: File, userId: string) {
  const supabase = createClient();
  const fileName = `${userId}/${Date.now()}-${file.name}`;
  const { data, error } = await supabase.storage
    .from('avatars')
    .upload(fileName, file, { upsert: true });
  if (error) throw error;
  return data.path;
}

Get a signed URL for displaying a private file:

const { data } = await supabase.storage
  .from('avatars')
  .createSignedUrl(filePath, 3600); // 1 hour expiry

Set storage policies the same way as table policies: every bucket should have RLS scoping access to the owning user.

Realtime Subscriptions (Optional)

For live features: kanban boards, chat, presence: Supabase realtime is the fastest path.

'use client';
import { useEffect, useState } from 'react';
import { createClient } from '@/lib/supabase/client';

export function LiveTasks({ projectId }: { projectId: string }) {
  const [tasks, setTasks] = useState([]);
  const supabase = createClient();

  useEffect(() => {
    const channel = supabase
      .channel(`tasks:${projectId}`)
      .on(
        'postgres_changes',
        { event: '*', schema: 'public', table: 'tasks', filter: `project_id=eq.${projectId}` },
        (payload) => {
          // Handle insert, update, delete
          console.log(payload);
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [projectId]);

  return <div>...</div>;
}

Realtime requires enabling replication on the table in the Supabase dashboard. Without it, the subscription succeeds but no events fire.

Common Gotchas

Forgetting RLS. The biggest security risk. Default-deny by enabling RLS, then add specific allow policies. Never ship with RLS off.

Server vs browser client confusion. The server client uses cookies for session; the browser client uses in-memory session. Mixing them causes "user is null" bugs that look like broken auth.

Skipping the middleware. Without auth-refreshing middleware, server components see stale or expired sessions. Symptoms: random logouts, "user is null" after navigation.

Service role key in client code. The service role key bypasses RLS. It must only run on the server. Putting it in a NEXT_PUBLIC_ variable or referencing it from a client component is a critical security incident.

Forgetting emailRedirectTo for signups. Without it, Supabase redirects to its own confirmation page, which doesn't carry the session into your app. Always specify the redirect.

Real-time without replication enabled. Subscribing to changes on a table without replication means silent failure. Enable replication in the dashboard for every table you subscribe to.

Free tier limits. 500 MB database, 1 GB storage, 2 GB egress. Easy to hit if you store user-uploaded files without CDN caching. Plan for Pro tier ($25/month) once you have meaningful users.

This is a shorter version of a guide I wrote at Frontkit Studio. The full post has the complete walkthrough.

How I built 14 accessible Next.js apps with Claude Code

Gaurav Guha — Fri, 30 Oct 2026 13:32:33 +0000

AI code generators write broken accessibility by default, but not because LLMs are incapable of writing semantic HTML. The issue is that an LLM does not know when it has produced inaccessible code, and most developers do not verify what it outputs.

I built 14 production Next.js applications with Claude Code over the last six months. Every single one passes WCAG 2.1 Level AA across roughly 350 unique screens, using Next.js 16, Tailwind CSS 4, and shadcn/ui. Every app passes axe-core with zero critical or serious violations.

This worked because I set up a verification workflow that catches Claude's mistakes the same way you would catch a junior engineer's mistakes.

The myth about AI and accessibility

The common claim on developer forums is that AI code generators cannot produce accessible code because LLMs hallucinate ARIA attributes and ignore semantic HTML.

That is half true. LLMs do hallucinate ARIA attributes. Claude has generated role="container" (which does not exist) and aria-pressed="yes" (which should be "true") right in front of me. I have watched it output buttons as divs, form inputs without labels, and contrast ratios failing at 2.1:1.

The flaw in the argument is the conclusion. AI generates broken code, but so do humans. Experienced developers catch their own mistakes because they review their work against a checklist and run automated tooling. Most teams using AI skip both.

The solution is not to stop using AI. It is to enforce a repeatable review discipline.

Step 1: Start with an accessibility-first system prompt

Claude Code follows the priorities defined in your system prompt. If you omit accessibility requirements, the model optimizes for visual layout and generation speed.

I add this block to CLAUDE.md in every project before asking Claude to write code:

# Accessibility requirements (NON-NEGOTIABLE)

Every component you write must pass WCAG 2.1 AA. Specifically:

1. Use semantic HTML before reaching for ARIA. <button> not <div onclick>.
   <nav> not <div role="navigation">. <main> not <div id="main">.

2. Every interactive element must work with keyboard alone. Tab to focus,
   Enter/Space to activate, Esc to close. Test by mentally walking through
   the tab order.

3. Every form input must have an associated <label>. Placeholders are
   not labels.

4. Color contrast: 4.5:1 for normal text, 3:1 for large text and UI
   components. Use the design tokens from globals.css; do not invent
   new colors.

5. Focus indicators must be visible against every background the
   component can sit on. Ring-2 with offset, never ring-1 with opacity.

6. Status changes must be announced to screen readers via aria-live
   or role="status". Toasts use sonner with role="status".

7. Never use color alone to convey meaning. Always pair color with
   icon or text.

8. Modals trap focus, return focus to trigger on close, close on Esc.
   Use shadcn Dialog (built on Radix), not custom implementations.

9. Touch targets are at least 44x44px on mobile. Use min-h-11 on tap
   targets that look smaller.

10. Test the following before marking anything complete:
    - Tab through every interactive element
    - Resize browser to 320px wide (no horizontal scroll)
    - Toggle dark mode (contrast still passes)
    - Run the page through axe DevTools (zero criticals)

Claude still makes mistakes with this in place, but they happen far less often, and the model fixes them faster when reminded of its own rules.

Step 2: Use shadcn/ui as the base instead of custom components

shadcn/ui wraps Radix UI primitives. Radix handles focus management, keyboard navigation, ARIA attributes, and screen reader announcements out of the box.

Whenever a screen needs a button, modal, dropdown, dialog, or popover, use the shadcn implementation. Never let Claude build a custom modal or dropdown from scratch. It will eventually drop the focus trap or miss the aria-expanded attribute.

Step 3: Run axe-core on every screen

After Claude generates a screen, run axe DevTools on the rendered page. It takes a few minutes and catches roughly 60% of automated accessibility issues.

To automate this in your test suite, use @axe-core/playwright:

import { test, expect } from "@playwright/test"
import AxeBuilder from "@axe-core/playwright"

test("dashboard has no a11y violations", async ({ page }) => {
  await page.goto("/dashboard")
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
    .analyze()

  expect(results.violations).toEqual([])
})

When this test fails, copy the exact violation details back into Claude Code and tell it to fix them. Claude is bad at preventing violations on the initial generation, but it is reliable at fixing them when given the exact failing rule.

Step 4: Run a manual keyboard test

Static tools miss dynamic interaction bugs. A screen can pass axe-core while remaining unusable without a mouse. For every screen:

Navigate to the page.
Press Tab repeatedly through every interactive element.
Check that the tab order follows the visual reading order.
Trigger actions using only the keyboard: Enter or Space for buttons, arrow keys for menus, Esc to dismiss overlays.
Watch for elements that trap focus inappropriately or drop focus entirely.

This takes about 90 seconds per view and catches broken dialog traps or menus that fail to focus their first item on open.

Step 5: Run a screen reader smoke test

Turn on VoiceOver on macOS (Cmd+F5) or NVDA on Windows and walk the main user flow. Check three things:

Meaningful labels: every interactive item announces a clear label, not just "button" or "edit text".
Dynamic updates: loading spinners, form error states, and success toasts trigger announcements.
Headings: the hierarchy is logical, starting with one h1, followed by h2 sections, without skipped levels.

Step 6: Test color contrast across all themes

shadcn relies on CSS custom properties for theming. A color pair that passes contrast in light mode can easily fail in dark mode.

The most frequent regression is muted-foreground placed on top of muted backgrounds. Check every theme permutation explicitly.

Common Claude mistakes and the fix prompts

Across hundreds of generated screens, Claude repeatedly falls into the same specific traps:

1. Clickable divs

Claude will build a card as a <div> with an onClick handler. It looks right visually, but screen readers and keyboards ignore it.

Prompt: "Make every clickable card a <button> or wrap it in a <Link> from next/link, never a div with onClick."

2. Skipped heading levels

Claude often puts an <h1> on the title and jumps immediately to <h3> for cards to match visual styling, violating WCAG 1.3.1.

Prompt: "Heading levels must be sequential. After h1, the next level can only be h2. After h2, only h2 or h3. Never skip a level."

3. Placeholders instead of labels

Inputs will get placeholder="Email address" with no <label> element. Once the user types, the placeholder disappears, and screen readers lose context.

Prompt: "Every form input must have a <label> element associated via htmlFor. Use the shadcn <Label> component. The placeholder is for example text only, never as the label."

4. Custom modals without focus traps

If Claude writes a modal without Radix primitives, tabbing escapes the overlay into background elements.

Prompt: "Always use the shadcn <Dialog> component for modals. Never build a custom modal. Radix Dialog handles focus trap, focus return, and Esc-to-close correctly."

5. Silent asynchronous updates

Claude generates a "Saving..." text label on submit, but omits an announcement region.

Prompt: "Status messages must be in a region with role='status' or aria-live='polite' so screen readers announce them. For toast notifications, use sonner which handles this automatically."

6. Relying purely on color

Inputs fail with a red border alone, without an error message or icon, which violates WCAG 1.4.1.

Prompt: "Status indicators must combine color, icon, and text. Failed inputs need a red border AND an error message AND an aria-invalid attribute. Successful submits need a green icon AND text AND a status announcement."

7. Hallucinated ARIA

Claude writes attributes that do not exist in the WAI-ARIA specification, such as aria-tooltip or aria-hidden="yes".

Prompt: "Pay especially close attention to attribute names and boolean values. Ensure every ARIA attribute matches the W3C specification exactly."

What cannot be delegated to Claude

Claude Code handled the bulk of the initial markup, but specific tasks required manual implementation:

Recharts SVGs: Chart graphics have no accessible fallback out of the box. You must write visually hidden <table> summaries alongside each chart so screen readers can consume the underlying dataset.
Dynamic announcement copy: Specific announcements like "Filter applied, showing 47 results" get missed by LLMs unless explicitly requested.
Physical screen reader listening: No automated tool replaces testing an interface with VoiceOver or NVDA to verify the spoken reading order.

This is a shorter version of a guide I wrote at Frontkit Studio. The full post has the complete walkthrough.

Supabase RLS Explained: Policies, Roles, and Common Security Mistakes

Gaurav Guha — Wed, 28 Oct 2026 13:33:04 +0000

Supabase gives the browser a key that talks straight to your database. There is no API server in the middle deciding who gets what, which means your Row Level Security (RLS) policies are your application's actual permission layer.

Most tutorials stop at auth.uid() = user_id. Real apps need roles, team tenancy, paid content access, and public pages with private drafts. Here is how RLS works in practice, five common architectural patterns, security mistakes to avoid, and how to test your rules before shipping.

How RLS Works in Supabase

Every request to the Supabase Data API runs as one of three Postgres roles:

anon: No signed-in user. RLS applies.
authenticated: A signed-in user's access token is present. RLS applies.
service_role: Your server, using a secret key. Bypasses RLS.

Postgres runs two checks for each incoming query:

Grants: Determine whether a role can run select, insert, update, or delete on the table at all.
Policies: Determine which specific rows that operation can read or modify.

On existing Supabase projects, new tables created in public start with all four operations granted to anon and authenticated. Adding policies does not revoke those default grants. Once RLS is enabled, access is default-deny, but you should explicitly clean up grants:

alter table public.deals enable row level security;

-- Take back the automatic grants, then give back only what the app needs.
revoke all on table public.deals from anon, authenticated;
grant select, insert, update, delete on table public.deals to authenticated;

The Four Policy Clauses

select: Uses using to check which rows a user can read.
insert: Uses with check to validate newly created rows.
update: Uses using to decide which rows can be updated, and with check to validate what the updated row looks like.
delete: Uses using to check which rows can be removed.

Two details catch people often:

An update statement fails if the user does not also have a select policy that lets them view the target row.
If an update policy omits with check, Postgres applies the using expression to both passes.

Multiple policies for the same operation combine with OR. If any single policy passes, the row is allowed.

Pattern 1: User-Owned Rows

For private user data like orders, notes, or bookmarks:

create policy "Customers read their own orders"
on public.orders for select
to authenticated
using ( (select auth.uid()) = user_id );

Notice there is no insert policy here. In a store, customers should not insert orders directly from the client. An order row should be created by a server-side webhook running with the service role after payment succeeds. The safest write policy is often having no client write policy at all.

Pattern 2: Immutable Roles

Many applications have roles: admin, editor, student, instructor. The naive approach puts a role column directly on profiles with an update policy allowing users to edit their own profile:

-- Looks harmless. It isn't.
create policy "Users update their own profile"
on public.profiles for update
to authenticated
using ( (select auth.uid()) = id );

This policy restricts rows, not columns. Any signed-in user can run this from their browser console:

await supabase.from('profiles').update({ role: 'admin' }).eq('id', user.id)

Because the row belongs to the user, the update succeeds. If your authorization logic relies on profiles.role, they are now an admin.

Instead, separate roles into a dedicated table that users cannot write to:

create table public.user_roles (
  user_id uuid primary key references auth.users (id) on delete cascade,
  role text not null default 'member' check (role in ('member', 'admin'))
);

alter table public.user_roles enable row level security;
revoke all on table public.user_roles from anon, authenticated;
grant select on table public.user_roles to authenticated;

create policy "Users read their own role"
on public.user_roles for select
to authenticated
using ( (select auth.uid()) = user_id );

-- No insert, update or delete policies. Role changes go through your server.

To check role status in other policies, write a helper function inside a private schema:

create schema if not exists private;

create function private.is_admin()
returns boolean
language sql
security definer
set search_path = ''
stable
as $$
  select exists (
    select 1 from public.user_roles
    where user_id = (select auth.uid()) and role = 'admin'
  );
$$;

revoke execute on function private.is_admin() from public;
grant usage on schema private to authenticated;
grant execute on function private.is_admin() to authenticated;

security definer allows the function to read user_roles without triggering infinite loops or needing broad read access. set search_path = '' stops search path hijacking, requiring fully qualified schema names inside the function.

If you must keep role on profiles, restrict permissions down to the column level:

revoke update on table public.profiles from authenticated;
grant update (full_name, avatar_url) on table public.profiles to authenticated;

Never Trust Sign-Up Metadata for Roles

Avoid assigning roles in triggers from user metadata:

-- Dangerous: the client decides the role.
coalesce(new.raw_user_meta_data ->> 'role', 'student')

raw_user_meta_data is supplied directly by the client during supabase.auth.signUp(). Anyone can send { options: { data: { role: 'admin' } } }. Always hardcode default roles in auth triggers:

create function private.handle_new_user()
returns trigger
language plpgsql
security definer
set search_path = ''
as $$
begin
  insert into public.profiles (id, full_name)
  values (new.id, new.raw_user_meta_data ->> 'full_name');

  insert into public.user_roles (user_id, role)
  values (new.id, 'member');

  return new;
end;
$$;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute function private.handle_new_user();

Pattern 3: Shared Team Tenancy

Checking whether a user has an account is not enough for multi-tenant apps. If public sign-up is open and any signed-in user can access rows, anyone can view private workspace data.

Use an explicit team membership table:

create table public.team_members (
  team_id uuid not null references public.teams (id) on delete cascade,
  user_id uuid not null references auth.users (id) on delete cascade,
  role text not null default 'member' check (role in ('member', 'admin')),
  primary key (team_id, user_id)
);

-- The primary key only indexes team_id. Policies filter on user_id.
create index team_members_user_id_idx on public.team_members (user_id);

create function private.user_team_ids()
returns setof uuid
language sql
security definer
set search_path = ''
stable
as $$
  select team_id from public.team_members
  where user_id = (select auth.uid())
$$;

create policy "Team members read deals"
on public.deals for select
to authenticated
using ( team_id in (select private.user_team_ids()) );

create policy "Team members add deals to their team"
on public.deals for insert
to authenticated
with check ( team_id in (select private.user_team_ids()) );

create policy "Team members update their team's deals"
on public.deals for update
to authenticated
using ( team_id in (select private.user_team_ids()) )
with check ( team_id in (select private.user_team_ids()) );

Using a security definer helper function here also avoids infinite recursion detected in policy errors when tables cross-reference each other.

Pattern 4: Access Gated by Enrollment

In an LMS or membership site, catalog metadata might be open, but paid lessons require validation:

create function private.enrolled_course_ids()
returns setof uuid
language sql
security definer
set search_path = ''
stable
as $$
  select course_id from public.enrollments
  where user_id = (select auth.uid())
    and status in ('active', 'completed')
$$;

create policy "Students read published lessons they can access"
on public.lessons for select
to authenticated
using (
  status = 'published'
  and (
    free_preview
    or module_id in (
      select m.id from public.modules m
      where m.course_id in (select private.enrolled_course_ids())
    )
  )
);

create policy "Instructors read lessons in their own courses"
on public.lessons for select
to authenticated
using (
  module_id in (
    select m.id from public.modules m
    join public.courses c on c.id = m.course_id
    where c.instructor_id = (select auth.uid())
  )
);

Ensure enrollments can only be inserted by your server webhook, not by client-side calls.

Pattern 5: Public Reads with Private Drafts

For publishing platforms where anonymous users can see live content, but creators can only see or edit their own drafts:

grant select on table public.posts to anon, authenticated;

create policy "Anyone reads published posts"
on public.posts for select
to anon, authenticated
using ( status = 'published' );

create policy "Authors read their own posts"
on public.posts for select
to authenticated
using ( (select auth.uid()) = author_id );

create policy "Authors edit their own unpublished posts"
on public.posts for update
to authenticated
using ( (select auth.uid()) = author_id and status <> 'published' )
with check ( (select auth.uid()) = author_id and status <> 'published' );

The with check clause prevents authors from setting their own post to published without proper review steps or permissions.

Keeping Policies Fast

Postgres evaluates policies across candidate rows. If written poorly, queries slow down drastically:

Wrap subqueries: Write (select auth.uid()) instead of auth.uid(). Wrapping it in a select makes Postgres evaluate it once per query instead of recalculating on every row.
Index foreign keys: Policies filter against user_id, team_id, or author_id. Ensure every column checked in a policy is indexed.
Specify the role with to: Using to authenticated tells Postgres to skip running the policy altogether for anon queries.

Testing Policies Manually and in CI

The Supabase Dashboard SQL editor runs queries as the superuser role, bypassing all RLS rules. A query working there does not mean your users can run it.

To test policies in SQL, wrap your test in a transaction that sets the active role and JWT context, then rolls back:

begin;
set local role authenticated;
set local request.jwt.claims to '{"sub":"USER-UUID-HERE","role":"authenticated"}';

-- Should return only that user's rows.
select id from public.deals;

-- Should update zero rows or fail. If it says UPDATE 1, you have a problem.
update public.user_roles set role = 'admin' where user_id = 'USER-UUID-HERE';

rollback;

If the update returns UPDATE 1, your policy allows users to overwrite restricted columns.

This is a shorter version of a guide I wrote on thefrontkit. The full post has the complete walkthrough.

shadcn/ui Accessibility Audit: 14 Components That Fail WCAG 2.2 AA

Gaurav Guha — Tue, 27 Oct 2026 13:30:01 +0000

If you are relying on shadcn/ui out of the box to pass a procurement review or accessibility audit, your app will not pass cleanly. While Radix UI handles the underlying keyboard and focus mechanics well, shadcn's default Tailwind classes and composition patterns break compliance on 14 out of 48 components.

The most common failure across the library is focus visibility. Radix gives you correct focus management, but shadcn's default styles use focus-visible:ring-1 ring-ring/50, which drops below the 3:1 non-text contrast ratio in most themes.

Here is the breakdown of what works, what fails, and how to patch the components in your codebase.

The 34 components that pass WCAG 2.2 AA

These pass WCAG 2.2 AA out of the box with the default install:

Layout and navigation: Accordion, Aspect Ratio, Breadcrumb, Card, Collapsible, Resizable, Scroll Area, Separator, Sheet, Sidebar.
Form primitives: Checkbox, Form, Input OTP, Label, Radio Group, Select, Switch, Textarea, Toggle, Toggle Group.
Feedback: Alert, Dialog, Popover, Progress, Skeleton, Sonner (Toast), Tooltip.
Display: Avatar, Badge, Calendar, Hover Card, Pagination, Table, Tabs.

These components inherit Radix UI's behavior without styling conflicts. Keep in mind that if you override --ring or --primary with low-contrast custom colors in your theme, you can still break these defaults.

9 components that need minor fixes

These components work mechanically, but their default configuration or styling fails specific criteria.

1. Button: focus ring contrast in default theme

The default Button uses focus-visible:ring-ring/50, which renders the focus indicator at 50% opacity. In light mode against a white background, this produces a contrast ratio of 2.4:1, below the WCAG AA threshold of 3:1 for non-text contrast.

In components/ui/button.tsx, update the focus classes:

// Before
"focus-visible:ring-ring/50 focus-visible:ring-[3px]"

// After
"focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-background"

This ensures a solid 2px ring at full opacity with an offset against the background color.

2. Input: placeholder contrast

The text-muted-foreground utility used for placeholder text falls below 4.5:1 in the default light theme (zinc-500 on white), failing WCAG 1.4.3.

Darken --muted-foreground in your theme, or override the placeholder color in components/ui/input.tsx:

"placeholder:text-zinc-600 dark:placeholder:text-zinc-400"

Do not rely on the placeholder as the only label. Pair the input with an explicit label or aria-describedby pointing to visible helper text to satisfy WCAG 3.3.2.

3. Slider: keyboard step too coarse

Radix Slider supports arrow keys and Page Up/Down for navigation, but shadcn does not expose a step prop in the default wrapper. It defaults to 1, which works for 0 to 100 percentages but fails for precision numeric inputs.

When using the Slider, pass an explicit step prop:

<Slider value={[value]} onValueChange={...} min={0} max={100} step={1} />

4. Command (Cmdk): missing aria-label on input

The cmdk primitive handles list navigation, but the shadcn wrapper does not provide a default aria-label on the search input. Screen readers announce the field as unlabelled "edit text".

In components/ui/command.tsx, add an accessible label to the input wrapper:

<CommandInput placeholder="Search..." aria-label="Search commands" />

5. Carousel (Embla): autoplay ignores reduced motion

The shadcn Carousel autoplay example does not check for the user's motion preferences. WCAG 2.3.3 requires animations triggered by interaction or page loads to respect user settings.

Disable the plugin when prefers-reduced-motion is active:

import Autoplay from "embla-carousel-autoplay"

const plugins = useMemo(() => {
  if (typeof window === "undefined") return []
  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches
  return reduceMotion ? [] : [Autoplay({ delay: 4000 })]
}, [])

<Carousel plugins={plugins}>...</Carousel>

6. Toast (Sonner): duration too short

Sonner defaults to a 4-second auto-dismiss window. WCAG 2.2.1 requires users to have sufficient time to read and interact with content.

Increase the default duration and allow pauses on interaction:

<Toaster
  duration={8000}
  closeButton
  richColors
  pauseWhenPageIsHidden
/>

For error states or critical alerts, set duration: Infinity so users must manually dismiss them.

7. Date Picker: month and year navigation touch targets

The Date Picker wraps Calendar inside a Popover. The month and year navigation buttons in the Calendar header use icons with small touch targets that fall short of WCAG 2.2 SC 2.5.8 (Target Size Minimum, 24x24px).

In components/ui/calendar.tsx, update the navigation button sizing:

// In components/ui/calendar.tsx, find the nav buttons and apply:
className="size-9 ..." // instead of size-7
aria-label="Previous month"

8. Menubar: submenu trigger expanded states

In some custom builds, the shadcn Menubar wrapper can drop the aria-expanded state on trigger elements. Inspect your DOM output in browser devtools to verify that aria-expanded="true|false" updates when submenus open and close.

9. Drawer (Vaul): focus restoration

If the element that opened a Vaul drawer unmounts while the drawer is open (such as opening a drawer from inside a dropdown menu that closes immediately), focus will drop to the document body when the drawer closes. Keep the trigger mounted in the DOM, or pass an explicit focus ref to restore focus on close.

5 components with major accessibility gaps

These components contain structural issues that will be flagged in any standard accessibility audit.

1. Combobox: incomplete ARIA roles

The Combobox pattern in shadcn is not a standalone component. It is composed of a Popover and a Command menu. The standard example in the documentation misses three required combobox attributes:

Missing aria-haspopup="listbox" on the trigger button.
Missing aria-expanded state on the trigger button.
Missing aria-controls pointing from the trigger to the list container.

Without these, screen readers treat the combobox as a standard button and do not announce state changes to the dropdown.

2. Data Table: missing captions, sort states, and live regions

The @tanstack/react-table implementation provided in the docs creates table markup without accessible headers or status regions:

The <table> element lacks a <caption>.
Pagination updates do not announce row ranges to screen readers.
Sortable column headers do not expose sort direction via aria-sort.
Selection checkboxes lack row-specific labels.

Patch your table implementation with these elements:

// Add caption
<Table>
  <caption className="sr-only">
    Customer list, {data.length} total customers
  </caption>
  ...
</Table>

// Add live region for pagination
<div aria-live="polite" className="sr-only">
  Showing rows {start} to {end} of {total}
</div>

// Sort state on column headers
<Button
  onClick={column.getToggleSortingHandler()}
  aria-label={`Sort by ${column.id}`}
  aria-sort={
    column.getIsSorted() === "asc" ? "ascending" :
    column.getIsSorted() === "desc" ? "descending" : "none"
  }
>
  {column.id}
</Button>

// Row selection labels
<Checkbox
  aria-label={`Select row for ${row.original.name}`}
  ...
/>

3. Context Menu: non-functional shortcut hints

shadcn Context Menu displays visual keyboard shortcut hints (like "Cmd+C") by default, but does not attach actual keyboard listeners for those combinations. Under WCAG 3.2.4, presenting an explicit shortcut label that fails to execute creates an inconsistent interface. Either bind the shortcut with a key listener or remove the shortcut hint text.

4. Chart: missing non-text alternatives

The Chart component wraps Recharts SVGs. Recharts renders raw SVG paths without alternative text, leaving screen readers with an empty container. Under WCAG 1.1.1, charts require a text or tabular equivalent.

Pair the chart with an accessible, visually hidden table representing the dataset:

<ChartContainer>
  <BarChart data={data}>...</BarChart>
  <table className="sr-only">
    <caption>Monthly revenue, 2026</caption>
    <thead><tr><th>Month</th><th>Revenue</th></tr></thead>
    <tbody>
      {data.map(d => <tr key={d.month}><td>{d.month}</td><td>{d.revenue}</td></tr>)}
    </tbody>
  </table>
</ChartContainer>

5. Input OTP: paste announcements

While the Input OTP component supports clipboard pasting, screen readers do not trigger individual input changes when a full code is pasted at once. Users relying on speech output get no confirmation that the code registered.

Add an aria-live status container next to the component to announce completion:

const [code, setCode] = useState("")
return (
  <>
    <InputOTP value={code} onChange={setCode} maxLength={6} />
    <div role="status" aria-live="polite" className="sr-only">
      {code.length === 6 ? "Verification code complete" : ""}
    </div>
  </>
)

This is a shorter version of a guide I wrote on thefrontkit. The full post has the complete walkthrough.

Practical ARIA cheat sheet for React and Next.js

Gaurav Guha — Mon, 26 Oct 2026 13:30:01 +0000

You're building a custom tab component or an icon-only button in React and the screen reader announces nothing useful. The fix is usually a handful of ARIA attributes, but you need to know which ones belong where.

Below is a concise reference that shows the exact JSX you can copy-paste into a Next.js or React project. It's organized by the UI pattern you're trying to solve, so you can jump straight to the code you need.

ARIA roles

Roles tell assistive technology what an element is. They override the element's native role, so use them only when there's no suitable HTML element.

Landmark roles

Landmarks let users jump between major sections. Prefer native tags (<header>, <nav>, <main>, etc.) because they already have implicit roles. Add an explicit role only when you can't use the semantic element.

HTML element	Implicit role	When to use ARIA instead
`<header>`	banner	Only if not using semantic HTML
`<nav>`	navigation	Multiple navs need `aria-label` to distinguish
`<main>`	main	Only if not using semantic HTML
`<aside>`	complementary	Only if not using semantic HTML
`<footer>`	contentinfo	Only if not using semantic HTML
`<section>`	region (if labeled)	Must have `aria-label` or `aria-labelledby`
`<form>`	form (if labeled)	Must have `aria-label` or `aria-labelledby`

// Good: Native elements with labels for multiple navs
<nav aria-label="Main navigation">
  {/* Primary nav items */}
</nav>
<nav aria-label="Footer navigation">
  {/* Footer links */}
</nav>

// Good: Named section
<section aria-labelledby="settings-heading">
  <h2 id="settings-heading">Account Settings</h2>
  {/* Settings content */}
</section>

Widget roles

When you build a component that has no native HTML counterpart, give it a role that matches its purpose.

Role	Purpose	Common usage
dialog	Modal or non-modal dialog	Modals, confirmation prompts, lightboxes
alertdialog	Dialog that requires immediate attention	Delete confirmation, unsaved changes warning
tablist / tab / tabpanel	Tabbed interface	Settings tabs, dashboard views
menu / menuitem	Action menu	Context menus, dropdown action menus
menubar / menuitem	Horizontal menu bar	Application menu bars
listbox / option	Selectable list	Custom select dropdowns, command palettes
combobox	Text input with popup list	Autocomplete, search suggestions
tree / treeitem	Hierarchical list	File browsers, nested navigation
grid / row / gridcell	Interactive data grid	Spreadsheet-like interfaces
toolbar	Group of controls	Text editor toolbars, formatting bars
tooltip	Descriptive popup	Hover/focus info popups
switch	Binary toggle	On/off toggles (distinct from checkbox)
status	Live region for status updates	Save confirmations, sync indicators
alert	Urgent live region	Error messages, warnings
progressbar	Progress indicator	File uploads, loading states

ARIA states and properties

States describe the current condition of an element; properties describe relationships.

Toggle and selection states

// Accordion: expanded/collapsed state
<button aria-expanded={isOpen} aria-controls="panel-1">
  Account Settings
</button>
<div id="panel-1" role="region" hidden={!isOpen}>
  {/* Panel content */}
</div>

// Checkbox: checked state
<div
  role="checkbox"
  aria-checked={isChecked}
  tabIndex={0}
  onClick={toggle}
  onKeyDown={(e) => e.key === ' ' && toggle()}
>
  {label}
</div>

// Switch/toggle: on/off
<button role="switch" aria-checked={isEnabled} onClick={toggle}>
  Dark mode: {isEnabled ? 'On' : 'Off'}
</button>

// Tab: selected state
<button role="tab" aria-selected={isActive} tabIndex={isActive ? 0 : -1}>
  General
</button>

// Menu item: checked (for toggle menu items)
<div role="menuitemcheckbox" aria-checked={isChecked}>
  Show notifications
</div>

// Radio-style selection
<div role="menuitemradio" aria-checked={isSelected}>
  Sort by name
</div>

// Tree item: expanded
<div role="treeitem" aria-expanded={isOpen} aria-level={2}>
  Components
</div>

Disabled and busy states

// Disabled: element exists but is not interactive
<button aria-disabled={!canSubmit} onClick={canSubmit ? handleSubmit : undefined}>
  Submit
</button>
// Note: aria-disabled keeps the element in tab order (unlike HTML disabled)
// Use HTML disabled when you want to remove from tab order entirely:
<button disabled={!canSubmit}>Submit</button>

// Busy: element is loading or updating
<div aria-busy={isLoading} aria-live="polite">
  {isLoading ? <Spinner /> : content}
</div>

// Current: indicates current item in navigation
<a href="/dashboard" aria-current="page">Dashboard</a>
<a href="/settings">Settings</a>

// Invalid: form field has error
<input
  aria-invalid={hasError}
  aria-describedby={hasError ? 'email-error' : undefined}
/>
{hasError && <span id="email-error" role="alert">Enter a valid email address</span>}

Progress and value states

// Progress bar
<div
  role="progressbar"
  aria-valuenow={65}
  aria-valuemin={0}
  aria-valuemax={100}
  aria-label="Upload progress"
>
  65%
</div>

// Indeterminate progress (no known completion)
<div role="progressbar" aria-label="Loading data">
  <Spinner />
</div>

// Slider
<input
  type="range"
  role="slider"
  aria-valuenow={volume}
  aria-valuemin={0}
  aria-valuemax={100}
  aria-label="Volume"
/>

Labeling and describing

These attributes are the ones you'll reach for most often.

`aria-label`

Use when there is no visible label. Perfect for icon-only buttons or inputs that only have a placeholder.

// Icon button with no visible text
<button aria-label="Close dialog" onClick={onClose}>
  <XIcon aria-hidden="true" />
</button>

// Search input without visible label
<input type="search" aria-label="Search templates" placeholder="Search..." />

// Multiple navigation landmarks
<nav aria-label="Main">...</nav>
<nav aria-label="Breadcrumb">...</nav>

`aria-labelledby`

Points to an element whose text is the label. Prefer this when a visible label already exists because it keeps the label consistent with what sighted users see.

// Dialog labeled by its heading
<div role="dialog" aria-labelledby="dialog-title" aria-modal="true">
  <h2 id="dialog-title">Delete Account</h2>
  <p>This action cannot be undone.</p>
</div>

// Form section labeled by a heading
<section aria-labelledby="billing-heading">
  <h3 id="billing-heading">Billing Information</h3>
  <input type="text" aria-label="Card number" />
</section>

// Can reference multiple elements
<button aria-labelledby="action-label item-name">
  <span id="action-label">Delete</span>
</button>
<span id="item-name">Project Alpha</span>
<!-- Screen reader announces: "Delete Project Alpha" -->

`aria-describedby`

Provides additional description that follows the name. Use for help text, error messages, or any supplemental info.

// Input with help text
<label htmlFor="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="password-help password-error"
/>
<span id="password-help">Must be at least 8 characters</span>
{error && <span id="password-error" role="alert">{error}</span>}

// Button with additional context
<button aria-describedby="delete-warning">Delete account</button>
<p id="delete-warning">This will permanently remove all your data.</p>

`aria-hidden`

Removes an element from the accessibility tree while keeping it visible. Good for decorative icons or background images. Never hide interactive controls.

// Decorative icon next to text
<button>
  <TrashIcon aria-hidden="true" />
  Delete
</button>

// Decorative background image
<div aria-hidden="true" className="background-pattern" />

// NEVER hide interactive elements
// Bad: <button aria-hidden="true">Submit</button>

Relationship attributes you'll need

When two elements are related but not nested, connect them with the following attributes.

aria-controls: identifies the element that a button (or similar) controls.
aria-owns: tells assistive tech that an element logically owns another element that lives elsewhere in the DOM.
aria-describedby and aria-labelledby (covered above) also act as relationship hooks.

Gotcha: aria-controls does not automatically hide or show the target element. You still need to manage visibility with hidden, CSS, or React state. The attribute is only a hint for screen readers about the relationship.

That's the core set of ARIA attributes you'll use in a typical React/Next.js UI. Copy the snippets, adjust the IDs and state variables to match your component, and you'll have accessible widgets without pulling in a heavyweight library.

This is a shorter version of a guide I wrote on thefrontkit. The full post has the complete walkthrough.

How to set up Drizzle ORM in a Next.js project

Gaurav Guha — Sun, 25 Oct 2026 13:30:02 +0000

You need a type-safe, low-bundle ORM for a Next.js app and want to get Drizzle wired up without hunting for scattered docs.

Step 1: Install Drizzle

npm install drizzle-orm postgres
npm install -D drizzle-kit

drizzle-orm is the runtime, drizzle-kit is the CLI for migrations, and postgres is the driver (swap for mysql2, better-sqlite3, etc. if you use another DB).

Add the connection string to .env.local:

DATABASE_URL=postgresql://user:password@host:5432/dbname

For Supabase copy the connection string from Project Settings → Database → Connection String and use the Connection Pooling URL (port 6543) for serverless deployments.

Step 2: Define the schema

Create db/schema.ts:

import { pgTable, uuid, text, timestamp, integer, boolean, jsonb } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  clerkId: text('clerk_id').notNull().unique(),
  email: text('email').notNull().unique(),
  firstName: text('first_name'),
  lastName: text('last_name'),
  avatarUrl: text('avatar_url'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
  updatedAt: timestamp('updated_at').notNull().defaultNow(),
});

export const projects = pgTable('projects', {
  id: uuid('id').primaryKey().defaultRandom(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  name: text('name').notNull(),
  description: text('description'),
  status: text('status', { enum: ['active', 'archived'] }).notNull().default('active'),
  settings: jsonb('settings').$type<{ color: string; visibility: 'public' | 'private' }>(),
  createdAt: timestamp('created_at').notNull().defaultNow(),
  updatedAt: timestamp('updated_at').notNull().defaultNow(),
});

export const tasks = pgTable('tasks', {
  id: uuid('id').primaryKey().defaultRandom(),
  projectId: uuid('project_id').notNull().references(() => projects.id, { onDelete: 'cascade' }),
  assigneeId: uuid('assignee_id').references(() => users.id),
  title: text('title').notNull(),
  description: text('description'),
  status: text('status', { enum: ['todo', 'in_progress', 'done'] }).notNull().default('todo'),
  priority: integer('priority').default(2),
  dueDate: timestamp('due_date'),
  completedAt: timestamp('completed_at'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});

// Relations
export const usersRelations = relations(users, ({ many }) => ({
  projects: many(projects),
  assignedTasks: many(tasks),
}));

export const projectsRelations = relations(projects, ({ one, many }) => ({
  user: one(users, { fields: [projects.userId], references: [users.id] }),
  tasks: many(tasks),
}));

export const tasksRelations = relations(tasks, ({ one }) => ({
  project: one(projects, { fields: [tasks.projectId], references: [projects.id] }),
  assignee: one(users, { fields: [tasks.assigneeId], references: [users.id] }),
}));

The schema lives in TypeScript, so you get full type inference in queries automatically.

Step 3: Create the database client

db/index.ts:

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

const connectionString = process.env.DATABASE_URL!;

// For Vercel / serverless: pool with prepared statements disabled
const client = postgres(connectionString, {
  prepare: false,
});

export const db = drizzle(client, { schema });

Setting prepare: false avoids prepared-statement issues in serverless functions where each invocation gets a fresh connection.

Step 4: Configure drizzle-kit

Add drizzle.config.ts at the project root:

import type { Config } from 'drizzle-kit';

export default {
  schema: './db/schema.ts',
  out: './db/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
} satisfies Config;

Step 5: Generate and run migrations

Create a migration from the current schema:

npx drizzle-kit generate

A .sql file appears in db/migrations/. Review it and edit if you need custom clauses or indexes.

Apply the migration:

npx drizzle-kit migrate

During early development you can skip the history step and push the schema directly:

npx drizzle-kit push

Use generate + migrate for production so you keep an audit trail.

Step 6: Query from server components

import { db } from '@/db';
import { projects } from '@/db/schema';
import { desc, eq } from 'drizzle-orm';

export default async function ProjectsPage({ params }: { params: { userId: string } }) {
  const userProjects = await db
    .select()
    .from(projects)
    .where(eq(projects.userId, params.userId))
    .orderBy(desc(projects.createdAt))
    .limit(20);

  return (
    <div>
      {userProjects.map((p) => (
        <div key={p.id}>{p.name}</div>
      ))}
    </div>
  );
}

userProjects is fully typed based on the schema.

Step 7: Joins with relations

const projectsWithTasks = await db.query.projects.findMany({
  where: eq(projects.userId, userId),
  with: {
    tasks: {
      where: eq(tasks.status, 'todo'),
      orderBy: desc(tasks.dueDate),
    },
    user: true,
  },
});

The result type includes tasks and user without manual joins.

Step 8: Inserts, updates, deletes

// Insert
const [newProject] = await db
  .insert(projects)
  .values({ userId, name: 'My new project' })
  .returning();

// Update
await db
  .update(projects)
  .set({ name: 'Renamed project', updatedAt: new Date() })
  .where(eq(projects.id, projectId));

// Delete
await db.delete(tasks).where(eq(tasks.id, taskId));

// Upsert
await db
  .insert(users)
  .values({ clerkId, email, firstName })
  .onConflictDoUpdate({
    target: users.clerkId,
    set: { email, firstName, updatedAt: new Date() },
  });

All operations return correctly typed results.

Step 9: Transactions

await db.transaction(async (tx) => {
  const [project] = await tx
    .insert(projects)
    .values({ userId, name: 'New project' })
    .returning();

  await tx.insert(tasks).values([
    { projectId: project.id, title: 'First task' },
    { projectId: project.id, title: 'Second task' },
  ]);
});

If any statement throws, the whole transaction rolls back.

Step 10: Server actions pattern

'use server';
import { db } from '@/db';
import { projects } from '@/db/schema';
import { auth } from '@clerk/nextjs/server';
import { revalidatePath } from 'next/cache';
import { z } from 'zod';

const createProjectSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
});

export async function createProject(formData: FormData) {
  const { userId } = await auth();
  if (!userId) throw new Error('Unauthorized');

  const data = createProjectSchema.parse({
    name: formData.get('name'),
    description: formData.get('description') || undefined,
  });

  const [project] = await db
    .insert(projects)
    .values({ userId, ...data })
    .returning();

  revalidatePath('/projects');
  return project;
}

Validate input with Zod, run the DB call (wrap in a transaction if needed), then revalidate the affected path.

Common gotchas

Connection pooling with serverless. If you leave prepare enabled, each function call tries to use prepared statements, which clashes with the pooler. Use the Supabase pooling URL (port 6543) and set prepare: false.
Forgetting relations(). Without explicit relation definitions, the with option in db.query.X.findMany fails. Define relations for every table you intend to join.
Schema drift between dev and prod. Relying on drizzle-kit push in production can overwrite manual changes. Stick to generate + migrate when deploying.

This is a shorter version of a guide I wrote on thefrontkit. The full post has the complete walkthrough.

How to add Stripe payments to a Next.js app with checkout, webhooks, and portal

Gaurav Guha — Sat, 24 Oct 2026 13:30:01 +0000

You need to let users pay with Stripe in your Next.js app, but you're not sure how to create the checkout flow, keep your DB in sync, and give customers a self-service portal.

Step 1: Create the Stripe account and products

Sign up at https://stripe.com and stay in test mode.
Products > Add product
Name: "Pro Plan"
Pricing: Recurring, $29/month (add an annual price at $290/year for the discount)
Save and copy the price ID (price_xxx)

Repeat for each tier (Starter, Pro, Enterprise). Grab two keys from the dashboard:

STRIPE_PUBLISHABLE_KEY (pk_test_... in test mode)
STRIPE_SECRET_KEY (sk_test_...)

You'll also need a webhook signing secret later.

Step 2: Install the SDK

npm install stripe @stripe/stripe-js

Add the keys to .env.local:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Create a Stripe client wrapper at lib/stripe.ts:

import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2025-10-29.acacia',
  typescript: true,
});

Step 3: Build the Checkout Session

Create a server action to start checkout:

'use server';
import { stripe } from '@/lib/stripe';
import { auth } from '@clerk/nextjs/server';
import { redirect } from 'next/navigation';

export async function createCheckoutSession(priceId: string) {
  const { userId } = await auth();
  if (!userId) throw new Error('Unauthorized');

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/billing/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/billing`,
    client_reference_id: userId,
    metadata: { userId },
    subscription_data: { metadata: { userId } },
    allow_promotion_codes: true,
    automatic_tax: { enabled: true },
  });

  if (session.url) redirect(session.url);
}

Key points:

client_reference_id links the session to your user.
metadata on the session and subscription gives redundant traceability.
allow_promotion_codes enables discount codes.
automatic_tax turns on Stripe Tax (requires setup).

Step 4: Trigger Checkout from the UI

'use client';
import { createCheckoutSession } from '@/app/actions/stripe';

export function CheckoutButton({ priceId, label }: { priceId: string; label: string }) {
  return (
    <form action={async () => { await createCheckoutSession(priceId); }}>
      <button type="submit">{label}</button>
    </form>
  );
}

When the button is clicked, the server action creates a session and redirects the user to Stripe-hosted checkout. After payment they return to /billing/success.

Step 5: Wire the Webhook

Stripe updates its own records; without a webhook your DB never knows a payment succeeded.

Create app/api/webhooks/stripe/route.ts:

import { headers } from 'next/headers';
import { stripe } from '@/lib/stripe';
import { db } from '@/lib/db';
import Stripe from 'stripe';

export async function POST(req: Request) {
  const body = await req.text();
  const signature = (await headers()).get('stripe-signature');

  if (!signature) {
    return new Response('Missing signature', { status: 400 });
  }

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    return new Response(`Webhook signature failed: ${err}`, { status: 400 });
  }

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object;
      const userId = session.client_reference_id || session.metadata?.userId;
      if (userId && session.subscription) {
        await db.subscription.upsert({
          where: { userId },
          create: {
            userId,
            stripeCustomerId: session.customer as string,
            stripeSubscriptionId: session.subscription as string,
            status: 'active',
          },
          update: {
            stripeCustomerId: session.customer as string,
            stripeSubscriptionId: session.subscription as string,
            status: 'active',
          },
        });
      }
      break;
    }

    case 'customer.subscription.updated': {
      const sub = event.data.object;
      await db.subscription.update({
        where: { stripeSubscriptionId: sub.id },
        data: {
          status: sub.status,
          currentPeriodEnd: new Date(sub.current_period_end * 1000),
          cancelAtPeriodEnd: sub.cancel_at_period_end,
        },
      });
      break;
    }

    case 'customer.subscription.deleted': {
      const sub = event.data.object;
      await db.subscription.update({
        where: { stripeSubscriptionId: sub.id },
        data: { status: 'canceled' },
      });
      break;
    }

    case 'invoice.payment_failed': {
      const invoice = event.data.object;
      // Notify the user, mark subscription as past_due, etc.
      break;
    }
  }

  return new Response('OK');
}

In the Stripe dashboard, add a webhook endpoint pointing to https://your-app.com/api/webhooks/stripe and subscribe to:

checkout.session.completed
customer.subscription.updated
customer.subscription.deleted
invoice.payment_failed
invoice.paid

Copy the webhook signing secret (whsec_...) into STRIPE_WEBHOOK_SECRET.

For local development, forward events with the Stripe CLI:

stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

The CLI prints a local whsec_... secret you can use during dev.

Step 6: Stripe Customer Portal

Instead of building your own subscription management UI, redirect users to Stripe's portal.

'use server';
import { stripe } from '@/lib/stripe';
import { auth } from '@clerk/nextjs/server';
import { db } from '@/lib/db';
import { redirect } from 'next/navigation';

export async function openCustomerPortal() {
  const { userId } = await auth();
  if (!userId) throw new Error('Unauthorized');

  const subscription = await db.subscription.findUnique({ where: { userId } });
  if (!subscription) throw new Error('No subscription');

  const session = await stripe.billingPortal.sessions.create({
    customer: subscription.stripeCustomerId,
    return_url: `${process.env.NEXT_PUBLIC_SITE_URL}/billing`,
  });

  redirect(session.url);
}

The portal lets users upgrade/downgrade plans, update payment methods, download invoices, and cancel. Enable the desired features in Stripe under Settings > Customer portal.

Step 7: Enable Stripe Tax (optional)

If you need to collect sales tax, enable Stripe Tax in the dashboard (Settings > Tax). Register the jurisdictions where you have nexus and assign tax codes to your prices. With automatic_tax: { enabled: true } in the checkout session, Stripe will calculate and collect tax automatically.

You can skip this step for a US-only, pre-revenue product and add it later when you cross a state's economic nexus threshold.

Step 8: One-Time Payments (non-subscription)

For a single purchase, set mode: 'payment' instead of 'subscription':

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout/success`,
  cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout`,
  client_reference_id: userId,
  metadata: { userId, type: 'one_time' },
});

The same webhook (checkout.session.completed) fires; grant lifetime access in your DB rather than creating a subscription record.

Common Gotchas

Skipping webhooks entirely. Users can pay, Stripe shows a successful charge, but your app never records it. Implement the webhook before you go live.
Mismatched environment keys. Using a live publishable key with a test secret (or vice-versa) causes "Invalid API Key" errors. Keep test and production keys separate.
Forgot to set client_reference_id. Without it you can't reliably map a checkout session back to your user in the webhook.
Webhook URL not reachable. In production the endpoint must be publicly accessible and use HTTPS; otherwise Stripe will keep retrying and eventually disable the webhook.
Tax settings not enabled but automatic_tax set. Stripe will reject the session creation; either enable Stripe Tax or remove the flag.

Address these issues early and the Stripe integration will stay in sync with your Next.js app.

This is a shorter version of a guide I wrote on thefrontkit. The full post has the complete walkthrough.

Why "Fix the UI Later" Costs You the Most

Gaurav Guha — Sun, 12 Apr 2026 05:56:49 +0000

If you build software long enough, you eventually say it.

"Let's just get it working. We will fix the UI later."

It feels reasonable. You want to prove the idea, validate the model, get something in front of users. (See also: frontend traps that slow SaaS launches.) The problem is that "later" almost never comes as a clean, cheap, neatly scoped phase.

Instead, that one sentence quietly creates some of the most painful and expensive work in your product's life.

Let's unpack why.

1. You are building on the wrong mental model

When you treat UI as decoration on top of "the real product," you design data flows, APIs and features without thinking about how people will actually experience them.

Common outcomes:

Endpoints that are hard to present in a clear interface
Features that require three different screens when one would do
Settings and permissions that make sense in code but not in a human's head

Later, when you try to "fix the UI," you discover that the only way to make the product feel simple is to untangle that earlier logic. Now it is not a paint job. It is surgery.

If you start with a system‑oriented UI in mind, even at a rough level, you get:

Clear mental models for users
Cleaner, more predictable flows
Backend decisions that match how people think

You do not need perfect design from day one, but you do need to stop thinking of UI as something you can bolt on at the end.

2. Redesigns multiply work instead of replacing it

When you "just ship" a rough UI and plan to revisit it, you end up building everything twice:

First version that sort of works
Second version that tries to fix everything at once

The catch is that the first version:

Already has users attached to it
Already has data saved in its shapes
Already has internal documentation, demos and habits formed around it

So the second version is not a clean replacement. It has to:

Preserve strange edge cases
Keep compatibility with old data and URLs
Be shipped in stages so you do not break everything at once

That is why redesigns feel so heavy. You are not just changing screens. You are working under the constraints of every quick decision you ever made.

A more sustainable approach is to ship on top of consistent patterns and components from day one. Then "redesigns" become:

Updating tokens and layouts
Swapping patterns in a handful of places

Not tearing out and rewriting large parts of the front end.

3. Inconsistent UX is a silent churn machine

When you build pages in an ad hoc way, you naturally optimize each one locally:

"This page could use a different button style"
"This flow needs its own special dialog"
"Let me just tweak this spacing a bit"

On the surface, each change improves the screen you are working on.

At the product level, it creates:

Different ways to do the same kind of action
Navigation that changes depending on where you are
Forms and tables that feel slightly different on every page

New users take longer to learn the product. Returning users feel a vague sense of friction. Support tickets go up because people cannot predict what the app will do.

None of this shows up as a single, obvious bug. It just drags down adoption and satisfaction.

System‑first UI flips that:

One pattern for primary actions
One pattern for forms and validation
One pattern for lists and tables

Every new page is faster to build and easier to understand because you are assembling from a small, consistent vocabulary instead of inventing a new one each time.

4. Tech debt in UI is still tech debt

Back end tech debt gets talked about a lot. Frontend tech debt often hides behind "we just need to clean up the styling."

Symptoms:

Styles duplicated across multiple components
Slight variations of buttons, modals and input fields
Custom hacks to fix spacing or layering in individual screens

Every change becomes risky because:

You are not sure which components are safe to touch
A fix for one screen breaks another
Refactoring feels like a redesign, not an improvement

Fixing this later is expensive because it requires:

Inventory of all your existing patterns
Merging and reconciling slightly different components
Unwinding one‑off overrides and hacks

If you start from a UI kit that already has a clear component and layout system, you avoid most of this:

Fewer one‑off overrides
Shared tokens and utilities
Known extension points

You can still move quickly, but you are moving quickly on top of guardrails.

5. "Temporary" UX survives much longer than you think

The "temporary" version you ship while you focus on other things will probably be around for a long time.

Why:

It is always hard to justify non‑critical work
Frontend refactors are hard to sell internally compared to new features
You get used to your own rough edges faster than your users do

Years later, you still have:

That awkward onboarding sequence
That modal that does too many things
That settings page nobody wants to touch

Each one creates daily friction for users and teams, but none of them are seen as individually important enough to fix. Together, they slow you down.

A small investment up front in solid starter flows and layouts can prevent a lot of this from ever existing.

6. System‑first kits vs ad hoc pages

So what is the alternative to "we will fix the UI later"?

It is not "spend six months designing a custom system before you write any code." That is just a different failure mode.

A more practical option is to:

Start your product from a system‑first kit that already knows what a SaaS app should look and feel like
Use proven patterns for app shells, forms, tables, settings and feedback
Configure and extend instead of inventing every piece from scratch

You get:

A coherent layout and navigation model
Consistent components across the whole app
Tokens and theming that keep design and code in sync
Accessibility handled as part of the system, not patched screen by screen

That is the idea behind something like thefrontkit's SaaS Starter Kit. It gives you:

An app shell with navigation, responsive layout and common pages
Ready‑made patterns for dashboards, settings and auth
A production-ready design token system for consistent theming
A starting point that is already built for production, not just screenshots

You still own your product's unique experience. The kit just takes the generic, error‑prone parts of UI off your critical path.

Explore the kits:

SaaS Starter Kit — App shell, dashboards, settings, auth, and token-driven theming.
AI UX Kit — Production-ready AI interfaces with streaming, feedback, and accessible patterns.

The real cost of "later"

When you say "we will fix the UI later," you are not just deferring polish. You are usually signing up for:

Data and logic that are hard to present clearly
Two implementations of every flow
A scattered user experience that depresses adoption
Hidden tech debt that makes every change slower

You do not need a perfect interface on day one. You do need a solid, system‑based foundation so that whatever you build in the early days is worth keeping and improving, not throwing away.

Starting from a production‑ready SaaS UI system is not about aesthetics. It is about buying back months of engineering time and giving your product a real shot at reaching and keeping the users it deserves.

TheFrontKit vs BoxyHQ — SaaS Starter Kit Comparison 2026

Gaurav Guha — Sun, 12 Apr 2026 05:56:08 +0000

TheFrontKit vs BoxyHQ: Which SaaS Starter Kit is Right for You?

If you're evaluating SaaS starter kits, you've probably come across BoxyHQ's open-source SaaS Starter Kit. It's one of the most popular enterprise-focused boilerplates on GitHub, with over 4,700 stars and a strong reputation for SAML SSO and SCIM directory sync.

But popularity and production-readiness aren't the same thing. Depending on what you're building—and who you're building it for—the right kit could save you months of work or leave you patching gaps for weeks.

This post compares thefrontkit's SaaS Starter Kit and BoxyHQ across the dimensions that actually matter when you're shipping a real product: UI completeness, design system, accessibility, AI readiness, and developer experience. (For a broader comparison, see Best SaaS Starter Kits 2026.)

Overview

BoxyHQ SaaS Starter Kit is a free, open-source (Apache 2.0) full-stack boilerplate built on Next.js, Prisma, and Tailwind CSS. Its core strength is enterprise identity: SAML SSO via SAML Jackson (now Ory Polis after Ory's acquisition of BoxyHQ in May 2025), SCIM directory sync, and audit logging via Retraced. The UI layer uses daisyUI for component styling and NextAuth.js for authentication.

thefrontkit SaaS Starter Kit is a frontend-focused kit built on Next.js, React, Tailwind CSS, and TypeScript. Its core strength is UI production-readiness: a complete set of accessible, token-driven components covering auth flows, app shells, dashboards, settings, forms, and notifications, with a production-ready design token system and optional AI UX Kit.

They solve different problems. BoxyHQ gives you enterprise identity plumbing. thefrontkit gives you the entire frontend foundation. Understanding where each one excels helps you make the right call.

Feature Comparison Table

Feature	thefrontkit	BoxyHQ
Stack	Next.js, React, Tailwind, TypeScript	Next.js 15, React 18, Tailwind, Prisma, TypeScript
Auth flows	Login, signup, reset, OTP — full UI recipes (bring your own auth provider)	Email/password, magic links, GitHub/Google OAuth, SAML SSO
SAML SSO / SCIM	Not included (pair with any SSO provider)	Built-in via SAML Jackson / Ory Polis — this is BoxyHQ's core strength
App shell	Production-ready sidebar, topbar, responsive layout, settings nav, dark mode	Basic layout structure
Dashboard components	Cards, charts, tables, activity feeds, stats	Minimal — team and SSO management screens
Settings pages	Account, billing, team, AI integrations, notifications, privacy	Team settings, SSO configuration
Design token system	Full token layer (color, spacing, radii, typography) via CSS custom properties	No token system — uses daisyUI utility classes
Token architecture	Production-ready token system with CSS custom properties	No token system
WCAG AA accessibility	Built-in: semantic HTML, ARIA, keyboard nav, focus management, contrast	Not verified — daisyUI provides basic semantics but no WCAG AA testing
Dark mode	Token-driven light/dark themes	Basic dark mode via daisyUI
AI-ready components	AI UX Kit available (streaming, citations, prompt UI)	Not included
Audit logs	Not included	Built-in via Retraced
Webhooks	Not included	Built-in via Svix
Billing	UI patterns included	Stripe in dependencies, but listed as "Coming Soon"
Database	Bring your own (frontend-focused)	PostgreSQL via Prisma
License	Commercial license	Apache 2.0 (free, open-source)
Best for	Teams that need a complete, accessible UI foundation	Teams that need enterprise SSO and identity compliance

Where TheFrontKit Wins

1. Component Completeness

The biggest gap in BoxyHQ's starter kit is the UI layer. It uses daisyUI—a Tailwind CSS plugin that provides pre-styled component classes—for its interface. That gets you buttons, cards, and modals, but it doesn't give you the production patterns every SaaS needs: responsive sidebar navigation, multi-step forms with validation, dashboard data layouts, notification systems, or settings page hierarchies.

With thefrontkit, those patterns ship ready to use:

import { MainSidebar } from "@/components/ui/composites/main-sidebar"

<MainSidebar
  activeMainNav={activeNav}
  activeSection={activeSection}
  onMainNavChange={setActiveNav}
  onSectionChange={setActiveSection}
  user={{ name: "Jane Doe", email: "jane@example.com" }}
  onUpgrade={() => router.push("/pricing")}
/>

You don't build your app shell. You configure it.

2. Production-Ready Design Token System

BoxyHQ has no design token layer. Colors, spacing, and typography are managed through Tailwind utilities and daisyUI theme classes. That works for prototyping, but it means rebranding requires hunting through components, and there's no single source of truth for design decisions.

thefrontkit ships with a full token system driven by CSS custom properties:

// tailwind.config.ts
colors: {
  primary: {
    50: "var(--color-primary-50)",
    600: "var(--color-primary-600)",
  },
}

To rebrand, you update token values, not component code. Designers and developers work from the same token vocabulary, so there's no translation layer.

3. Accessibility (WCAG AA)

This is where the difference matters most for production apps. BoxyHQ's UI layer (daisyUI + react-daisyui) provides basic HTML semantics, but there's no accessibility testing infrastructure in the project—no axe-core, no pa11y, no documented WCAG compliance.

thefrontkit is built on accessibility-focused primitives from the ground up:

Semantic HTML elements (no clickable <div>s)
Proper roles, labels, and ARIA attributes on every component
Visible focus rings and full keyboard navigation
WCAG AA color contrast in both light and dark modes
Focus management that moves to the first error on form submission
Accessible error announcements for screen readers

If you're selling to enterprises, accessibility compliance (VPAT, Section 508, EN 301 549) is increasingly a hard requirement in procurement. Starting with WCAG AA built in saves you from a painful retrofit later.

4. AI-Ready Patterns

If your SaaS includes AI features—chat interfaces, streaming responses, prompt builders, citation blocks—thefrontkit offers an AI UX Kit that pairs directly with the SaaS Starter Kit. Same design tokens, same component architecture, same accessibility standards.

BoxyHQ has no AI-related components. (BoxyHQ the company has a separate llm-chat repository, but it's not part of the starter kit.)

5. Developer Experience for Frontend Teams

BoxyHQ is a full-stack kit. That's both a strength and a tradeoff. It bundles Prisma, PostgreSQL, NextAuth, Svix, Retraced, and SAML Jackson into one project. If you need all of those, it saves integration time. But reviews note a developer experience rating of roughly 6/10 due to the enterprise complexity, and the learning curve for understanding all the moving parts is steeper.

thefrontkit is deliberately frontend-focused. You bring your own auth provider, your own database, your own backend. The kit handles the UI patterns and design system. This makes it simpler to adopt and easier to integrate into an existing stack.

Where BoxyHQ Fits

BoxyHQ is the stronger choice if your primary requirement is enterprise identity infrastructure:

SAML SSO is BoxyHQ's core competency. SAML Jackson (now Ory Polis) is a mature, battle-tested implementation used in production by enterprise teams. If your first customer requires SAML SSO and SCIM, BoxyHQ gets you there faster.
Audit logging via Retraced gives you "who did what, when" tracking out of the box—a compliance requirement for many enterprise buyers.
Directory sync (SCIM) automates user provisioning and de-provisioning from identity providers like Okta and Azure AD.
Open-source (Apache 2.0) means no license cost and full control over the codebase. For teams that prioritize open-source infrastructure, this matters.
Webhooks via Svix provide event-driven architecture for team and user lifecycle events.

If enterprise compliance and identity management are your primary blockers, BoxyHQ solves those problems well. The UI layer is secondary to its mission.

Pricing

BoxyHQ SaaS Starter Kit is free and open-source under Apache 2.0. Enterprise support, managed SAML, and related services are available through Ory's commercial offerings.

thefrontkit SaaS Starter Kit uses a commercial license. You get the full component library, design tokens, and AI UX Kit add-on. See pricing for current plans.

The real cost equation isn't the kit price—it's the engineering time you save or spend. A free kit that requires 4–6 weeks of UI work to reach production quality may cost more than a commercial kit that's ready on day one.

Verdict + CTA

Here's the simple version:

Choose BoxyHQ if enterprise SSO, SCIM, and audit logs are your primary launch requirements and you're comfortable building your own UI layer on top.
Choose thefrontkit if you need a complete, accessible, token-driven frontend foundation and want to ship a production-quality SaaS UI in weeks instead of months.

For many teams, the answer is both approaches combined: use thefrontkit for your entire frontend—auth flows, app shell, dashboard, settings, design system—and integrate a dedicated SSO provider (including BoxyHQ's SAML Jackson / Ory Polis) on the backend when enterprise customers require it.

The two kits aren't direct competitors. They solve different layers of the same problem. The question is which layer is your bottleneck.

Ready to skip the frontend boilerplate? Explore the SaaS Starter Kit and start building your product on a production-ready foundation.

Why Accessibility Comes First in SaaS & AI

Gaurav Guha — Sun, 12 Apr 2026 05:54:56 +0000

Most SaaS and AI teams optimize for speed: ship features, get users, iterate. In that rush, accessibility becomes a "later" problem—until it turns into a growth, support, and legal problem.

Accessibility isn't just compliance. It's a practical way to ship a product that works reliably for more people, on more devices, in more contexts—without expensive rework.

📈 Accessibility Is a Business Advantage

Expand your market reach: Stop silent churn from users who rely on keyboard navigation or screen readers.
Build brand trust: B2B procurement and security reviews often include accessibility requirements.
Reduce legal and operational risk: Retrofits are 10x more expensive than building it right the first time.
Improve UX for everyone: Clear hierarchy, better forms, and predictable navigation help every single user.

🔍 What Accessibility Looks Like in Real UI

Keyboard navigation: Complete core flows with Tab, Enter, and Esc.
Focus management: Visible focus rings that move predictably into modals and menus.
Forms: Labels, help text, and error summaries that screen readers can actually announce.
AI-Specific UX:
- Streaming responses: Use live regions so screen readers aren't overwhelmed. (See the AI UX Kit for production-ready implementations.)
- Citations: Keyboard-accessible reference links.
- Markdown: Navigable code blocks and lists.

🛑 Common Mistakes to Avoid

Clickable divs instead of semantic <button> or <a> tags. (See how to customize UI kits without breaking accessibility.)
Invisible focus rings (removed for "aesthetic" reasons).
Modals without focus traps (users get lost behind the overlay).
Contrast failures in Dark Mode.
AI layout shifts that break keyboard navigation when citations load late. (Learn about building production-ready AI interfaces.)

✅ Practical Day-One Checklist (WCAG AA)

Use semantic elements: button, label, input, fieldset.
Guarantee visible focus states.
Support keyboard flows: Especially for menus, tabs, and tables.
Validate contrast: Check both light and dark themes.
Respect reduced motion: Use CSS media queries for animations.

🚀 How thefrontkit Helps You Ship Faster

Accessibility doesn't need to slow you down if your baseline components are built correctly from the start.

Explore Accessible Foundations:

AI UX Kit — Built with Radix & shadcn/ui for accessible streaming and prompt flows.
SaaS Starter Kit — A production-ready shell with accessible auth, settings, and tables.

❓ FAQ

What does WCAG AA mean for SaaS?

It's the gold standard for accessibility, ensuring your app is perceivable, operable, and understandable for users with disabilities.

Does accessibility slow down development?

Only if you retrofit. Using accessible primitives like Radix UI (used in thefrontkit's AI UX Kit and SaaS Starter Kit) actually speeds up development by providing the logic for you.

How do I make AI chat accessible?

Focus on aria-live regions for streaming text and ensuring all interactive citations are reachable via keyboard. The AI UX Kit includes production-ready implementations of accessible AI chat interfaces.

What Is WCAG 2.1 AA? A Plain-Language Guide for Developers and Product Teams

Gaurav Guha — Thu, 09 Apr 2026 14:24:39 +0000

What Is WCAG 2.1 AA?

WCAG 2.1 AA is a set of technical standards that define how to make web content accessible to people with disabilities. WCAG stands for Web Content Accessibility Guidelines. The "2.1" is the version number. The "AA" is the conformance level.

When a company says "our product meets WCAG AA," they mean their website or application follows the success criteria defined in this standard at the A and AA levels. It's the most commonly referenced accessibility benchmark in legal requirements, procurement contracts, and corporate accessibility policies worldwide.

The standard is published by the World Wide Web Consortium (W3C), the same organization that maintains HTML, CSS, and other web standards. It's not a law itself, but laws in dozens of countries point to it as the definition of "accessible."

The Three Conformance Levels: A, AA, AAA

WCAG defines three levels of conformance, each building on the one below it:

Level A (Minimum)

The bare minimum for accessibility. If your site fails Level A criteria, it's likely unusable for some people with disabilities.

Examples of Level A requirements:

Images have alt text
Videos have captions
All functionality works with a keyboard
Page has a title
Form fields have labels

Level AA (Standard)

The level that most laws, regulations, and enterprise contracts require. AA includes all Level A criteria plus additional requirements for color contrast, text resizing, consistent navigation, and more.

Examples of Level AA requirements (in addition to Level A):

Text has at least 4.5:1 color contrast ratio
Text can be resized to 200% without breaking
Content reflows at 320px width without horizontal scrolling
Focus indicators are visible on all interactive elements
Error messages suggest corrections
Consistent navigation across pages

Level AAA (Enhanced)

The highest level. AAA is aspirational for most products. Meeting every AAA criterion across an entire application is rarely practical or required. Some specific features or pages may meet AAA, but full AAA conformance is not the standard that laws or contracts typically demand.

Examples of Level AAA requirements (in addition to AA):

7:1 color contrast for text
Sign language interpretation for video
No timing limits on any interaction
Context-sensitive help available on every page

The bottom line: When someone says "accessible," they almost always mean WCAG 2.1 Level AA. That's the target.

The Four Principles of WCAG

Every WCAG criterion falls under one of four principles, summarized by the acronym POUR:

Perceivable

Users must be able to perceive the content. Information can't be invisible to all of a user's senses.

This covers text alternatives for images, captions for video, sufficient color contrast, and content that adapts to different display settings (zoom, orientation, text spacing).

Operable

Users must be able to operate the interface. Every interaction must be possible through multiple input methods.

This covers keyboard accessibility, enough time to complete tasks, no content that causes seizures, clear navigation, and visible focus indicators.

Understandable

Users must be able to understand both the content and how the interface works. The UI should be predictable and help users avoid and correct mistakes.

This covers page language declarations, consistent navigation, meaningful error messages, and labels that describe their inputs.

Robust

Content must work with current and future assistive technologies. The code must be clean enough that screen readers, voice control, and other tools can interpret it correctly.

This covers valid HTML, proper ARIA attributes, and status messages that get announced without stealing focus.

For a complete criterion-by-criterion checklist, see WCAG AA Checklist for Web Apps.

Who Does WCAG Apply To?

Legally

Accessibility laws vary by country, but most reference WCAG 2.1 AA directly or indirectly:

United States:

ADA (Americans with Disabilities Act): Doesn't mention WCAG explicitly, but courts consistently use WCAG 2.1 AA as the benchmark. The Department of Justice published a final rule in 2024 requiring state and local government web content to meet WCAG 2.1 AA.
Section 508: Requires federal agencies and their vendors to meet accessibility standards based on WCAG 2.0 AA (updated to reference 2.1 in practice).

European Union:

European Accessibility Act (EAA): Requires products and services (including websites and mobile apps) to be accessible. Takes effect June 2025. References EN 301 549, which maps directly to WCAG 2.1 AA.
Web Accessibility Directive: Already requires public sector websites in EU member states to meet WCAG 2.1 AA.

Canada:

Accessible Canada Act: Sets accessibility standards for federally regulated organizations. Provincial laws (like AODA in Ontario) require WCAG 2.0 AA for large organizations.

United Kingdom:

Equality Act 2010 and Public Sector Bodies Accessibility Regulations 2018: Require public sector websites to meet WCAG 2.1 AA.

Australia:

Disability Discrimination Act 1992: Has been applied to web accessibility cases. Australian government websites must meet WCAG 2.0 AA minimum.

Contractually

Even where the law is ambiguous, enterprise procurement is not. Most B2B SaaS companies encounter WCAG AA as a hard requirement in:

RFPs and vendor assessments: Enterprise buyers include accessibility requirements in procurement documents. If you can't demonstrate WCAG AA compliance, you lose the deal.
VPATs (Voluntary Product Accessibility Templates): Enterprise customers request these to evaluate your product's accessibility. A VPAT documents which WCAG criteria your product meets.
Customer contracts: Large customers increasingly include accessibility clauses in their service agreements.

For more on how accessibility affects enterprise sales, see Accessibility for Startup Founders and Win RFPs with Accessibility Receipts.

WCAG 2.1 vs 2.0 vs 2.2

WCAG 2.0 (December 2008)

The original version. 61 success criteria across three levels. Still referenced in some older laws and contracts. Does not address mobile accessibility or cognitive disabilities adequately.

WCAG 2.1 (June 2018)

Added 17 new success criteria to 2.0, primarily addressing:

Mobile accessibility: Orientation, pointer gestures, motion actuation
Low vision: Reflow, non-text contrast, text spacing
Cognitive disabilities: Identify input purpose, status messages

WCAG 2.1 is backward-compatible with 2.0. If you meet 2.1 AA, you automatically meet 2.0 AA.

This is the version most current laws and contracts reference.

WCAG 2.2 (October 2023)

Added 9 more success criteria, including:

Focus Not Obscured: Focused elements must not be completely hidden behind sticky headers, modals, or other content
Dragging Movements: Functionality that uses dragging must have a non-dragging alternative
Target Size (Minimum): Interactive targets must be at least 24x24 CSS pixels (with exceptions)
Consistent Help: Help mechanisms appear in the same location across pages
Accessible Authentication: Login doesn't require cognitive function tests (like remembering a password without paste support)

WCAG 2.2 is also backward-compatible. Meeting 2.2 AA means you meet 2.1 AA and 2.0 AA.

Which Version Should You Target?

Target WCAG 2.1 AA as your baseline. This is what most laws and contracts require right now. If you can also address the WCAG 2.2 criteria (especially focus not obscured, target size, and accessible authentication), do it. They're practical improvements that make your product genuinely better.

What Disabilities Does WCAG Address?

WCAG criteria collectively address a wide range of disabilities:

Disability Category	Examples	Key WCAG Areas
Visual	Blindness, low vision, color blindness	Alt text, color contrast, screen reader support, text resizing, reflow
Auditory	Deafness, hard of hearing	Captions, transcripts, visual alternatives to audio cues
Motor	Limited fine motor control, paralysis, tremors	Keyboard accessibility, target sizes, no timing pressure, pointer alternatives
Cognitive	Learning disabilities, memory issues, attention disorders	Clear language, consistent navigation, error prevention, predictable behavior
Neurological	Seizure disorders, vestibular disorders	No flashing content, reduced motion support

Importantly, many accessibility improvements help everyone, not just people with diagnosed disabilities. Keyboard navigation benefits power users. Captions help people in noisy environments. Good contrast helps everyone reading in sunlight. Clear error messages help every user who makes a typo.

Common WCAG AA Failures in Web Applications

These are the criteria that web apps fail most often:

1. Insufficient Color Contrast

The single most common failure. Body text needs 4.5:1 contrast, and most gray-on-white or light-on-light color schemes don't meet this. Check every text color in both light and dark mode.

2. Missing Keyboard Navigation

Custom components (dropdown menus, date pickers, modals, sliders, tabs) built without keyboard support. If you can't Tab to it and activate it with Enter or Space, it fails.

3. Missing or Generic Alt Text

Images with no alt attribute, or alt text like "image" or "photo" that doesn't describe the content. Decorative images should use alt="" to be skipped by screen readers.

4. Form Fields Without Labels

Using placeholder text as the only label. Placeholders disappear when users type, leaving them with no indication of what the field expects. Every input needs a visible <label>.

5. No Visible Focus Indicator

Removing the browser's default focus outline with outline: none and not replacing it with a custom focus style. Keyboard users can't see where they are on the page.

6. Dynamic Content Not Announced

Toast notifications, inline error messages, loading states, and live updates that appear visually but aren't announced to screen readers. Use aria-live, role="status", or role="alert".

7. Missing Page Titles

Pages with generic titles like "Dashboard" on every page, or no title at all. Each page needs a unique, descriptive title.

8. Modals That Don't Trap Focus

Opening a modal but allowing Tab to move focus to elements behind it. When a modal is open, focus should be trapped inside it until it's closed.

How to Get Started with WCAG AA Compliance

Step 1: Audit Your Current State

Run an automated scan with axe DevTools or Lighthouse. This catches about 30-40% of accessibility issues. Then do a manual keyboard test on your main user flows.

Step 2: Fix the High-Impact Issues First

Start with contrast, keyboard navigation, and form labels. These affect the most users and are the most commonly tested by enterprise customers.

Step 3: Build Accessibility Into Your Component Library

Don't fix accessibility page by page. Fix it at the component level so every instance is accessible. If your Button component is accessible, every button in your app is accessible.

Step 4: Use Pre-Built Accessible Components

Libraries like shadcn/ui (built on Radix UI), Headless UI, and React Aria handle the complex accessibility patterns for you. The thefrontkit SaaS Starter Kit and AI UX Kit are built on shadcn/ui and Radix, with WCAG AA compliance verified across every component.

Step 5: Test Continuously

Add eslint-plugin-jsx-a11y to your linter. Include axe-core in your integration tests. Test with a screen reader (VoiceOver on Mac, NVDA on Windows) at least once per release cycle.

For a detailed, criterion-by-criterion implementation guide, see WCAG AA Checklist for Web Apps.

WCAG AA and SaaS Products

If you're building a SaaS product, WCAG AA compliance isn't just about doing the right thing (though it is). It's a business requirement that directly affects your ability to sell:

Enterprise deals require it. Most enterprise procurement processes include accessibility in their evaluation criteria.
Government contracts require it. Section 508 (US) and equivalent laws in other countries mandate it for any software used by government agencies.
Lawsuits are increasing. ADA web accessibility lawsuits in the US have grown every year. SaaS products are not exempt.
It's cheaper to build it in than to retrofit. Fixing accessibility after launch costs 10-100x more than building it in from the start.

The most efficient path is to start with components that are already accessible. The thefrontkit SaaS Starter Kit ships with WCAG AA compliance built into every component: auth screens, dashboard layouts, data tables, forms, and settings pages. You start with a compliant foundation and maintain compliance as you build on top of it.

For more on the business case, see:

Start accessible from day one: View SaaS Starter Kit | View AI UX Kit | WCAG AA Checklist

Standardize Next.js Frontends Across Clients

Gaurav Guha — Thu, 09 Apr 2026 14:23:51 +0000

If you run an agency that builds client products on Next.js, you know the pattern.

Every new project gets a fresh repo. A new layout. New components that look a lot like the last project but are just different enough to be annoying. By project five or six, you have five or six "standards." Nobody is sure which one to use for the next one.

The problem is not that clients want different things. They do. The problem is building a new frontend standard from scratch for every engagement instead of reusing a single, flexible baseline.

This post is about how to standardize your Next.js frontend so you can deliver faster and more consistently without making every client site look the same.

1. Why agencies end up with many "standards" instead of one

Common pattern:

Client A wants a dashboard. You build layout, sidebar, tables, forms.
Client B wants a different look. You tweak the layout, swap components, adjust spacing.
Client C wants something "fresh." You start again with a new structure but similar needs.

Over time you have:

Several layout patterns that are almost the same
Inconsistent tokens and spacing across projects
No single "source of truth" for how your agency builds Next.js frontends

Each project is a bit faster than building from zero, but you are still reinventing structure and patterns. The cost shows up in:

Onboarding time ("which starter do we use for this one?")
Maintenance ("we have three versions of the same modal")
Client handoffs ("here is the repo, good luck with the custom bits")

You do not need more flexibility per project. You need one clear standard that you can theme and extend per client so that "different" means colors and content, not a new architecture every time.

2. Standardize structure, not pixels

The goal is not to make every client site look identical. It is to make every client site built the same way under the hood.

Standardize:

App shell. One layout model: sidebar or top nav, main content area, responsive behavior. Same structure, different branding.
Auth and account flows. Logged out vs logged in, settings, profile. Same flows, different copy and styling.
Core components. Buttons, forms, tables, modals, cards. Same behavior and accessibility, different themes.
Tokens. Colors, spacing, typography, radius. One token system; each client gets a theme that maps to it.

What stays custom per client:

Brand colors, fonts, and visual style
Copy, imagery, and content
Feature set and pages
Integrations and domain-specific workflows

So "standardize" means: one shared structure and component set, many themes and configurations. That is how you get "one starter, many clients" without everything looking the same.

3. One starter, many clients

The leverage comes from reusing the same foundation across clients:

Same layout and navigation patterns
Same form and table patterns
Same accessibility and keyboard behavior
Same token system so theming is a config change, not a rewrite

For each new client you:

Clone or branch from the same starter
Apply their brand (tokens, fonts, assets)
Add or remove pages and features
Deploy

You are not starting from a blank page. You are configuring a known system. That cuts down on:

"How did we do this on the last project?"
Inconsistent quality and accessibility across engagements
Long ramp up for new devs who have to learn yet another agency "standard"

One starter, many clients does not mean one design. It means one system that you theme and extend per client.

4. Why accessibility belongs in the standard

If your clients ever work with larger companies, government, or regulated industries, they will be asked about accessibility. (See how accessibility receipts win RFPs.) If you standardize on a frontend that already handles the basics, you avoid:

Last minute a11y patches per project
Different levels of compliance across clients
Awkward conversations when a client says "we need to pass an audit"

So your standard should include:

Keyboard navigation and focus management
Contrast and color use that meet WCAG AA
Labels, structure, and live regions where needed

Then every client project gets the same baseline. You do not have to re‑explain or re‑implement it. And when a client or their buyer asks "how do you handle accessibility?" you can point to evidence: keyboard tests, contrast info, or a short report. That is what turns "we care about accessibility" into "here is how we meet the bar."

5. Tokens and themes: same system, different look

The way you keep "one standard" but "many looks" is tokens and themes.

Tokens are named design decisions: primary color, spacing scale, font family, border radius. Your starter defines a full set.
Themes are different values for those tokens: Client A gets blue and tight spacing, Client B gets green and loose spacing. Same components, different token values.

So you are not maintaining three separate design systems. You have one system with many theme files. New client means new theme (and maybe a few overrides), not a new component set.

If your starter includes a production-ready design token system, then design and code stay in sync across clients. Everyone works from the same token vocabulary. That reduces "the spec says one thing, the app shows another" and keeps handoffs predictable.

6. What you give up (and what you gain)

You give up:

The idea that every project is a blank canvas
Fully custom, one‑off layouts and components for every client
"We will fix the structure later" and ending up with another ad hoc standard

You gain:

Faster delivery. Same shell, same patterns, same a11y. You spend time on client‑specific logic and content, not reinventing layout and components.
Easier onboarding. New devs learn one system. They see the same patterns on the next project.
Consistent quality. Accessibility and UX are built into the standard, not patched per project.
Simpler handoffs. Clients get a codebase that follows a clear structure and token system, not a pile of custom one‑offs.

Agencies that standardize on a single Next.js frontend baseline do not sell "template" sites. They sell faster, more predictable delivery and consistent quality. The "standard" is how you deliver that.

7. How to adopt a standard without a big rewrite

You have a few paths.

Option A: Extract a standard from your best project.

Pick the cleanest, most recent client build. Document its structure, components, and tokens. Use it as the base for the next project. Refine as you go. This works but takes time and discipline, and the first "standard" may still have gaps (e.g. accessibility, tokens).

Option B: Build a standard from scratch.

Dedicate time to building the perfect agency starter: layout, components, tokens, accessibility, docs. This is a significant investment and may delay client work. (Compare the tradeoffs in SaaS Starter Kit vs Building from Scratch.)

Option C: Start from a production‑ready starter.

Use a Next.js starter that already has an app shell, auth and account flows, tokens, and accessibility built in (and ideally evidence/receipts). Theme it per client. Extend where needed. You get a standard without building it yourself.

Option C is what thefrontkit is built for. The SaaS Starter Kit gives you:

An app shell with layout, navigation, and responsive behavior
Auth and account‑style flows, settings, tables, forms
Token-based theming with a production-ready architecture
WCAG AA oriented components and accessibility evidence you can use with clients

You standardize on one foundation. Each client gets their own theme and feature set. You spend less time on structure and more on what makes each engagement valuable. And when a client or their buyer asks about accessibility, you have something concrete to show.

Explore the kits:

SaaS Starter Kit — App shell, auth, settings, tables, and token-based theming for client work.
AI UX Kit — Add AI flows to client projects with accessible prompt flows and streaming UI.

8. One starter, many clients, with receipts

The aim is not to make every client site look the same. It is to make every client site built the same way: one layout model, one component set, one token system, one accessibility baseline. Different branding and features, same quality and delivery model.

That is how agencies can standardize their Next.js frontend without sacrificing variety: one starter, many clients, with evidence when it matters.