Supabase + Claude Code: the complete guide to AI-assisted full-stack development

Supabase (Postgres + Auth + Storage + Edge Functions + Realtime) and Claude Code (AI coding agent) pair exceptionally well. Supabase's SQL-first approach means you can describe what you want in plain English and the agent translates it to Postgres DDL, RLS policies, and TypeScript types with high accuracy. This guide covers the full stack — from initial schema design to production edge functions. Why this pairing works ----------------------- Supabase has excellent documentation, stable TypeScript client APIs, and clear patterns for auth, data, and storage. Claude Code has read a lot of Supabase documentation in its training data and knows the current patterns (@supabase/ssr for Next.js, Row Level Security patterns, etc.). The result: you can describe a feature in plain English and get working code that usually requires one or two revisions, not five or ten. Compared to setting up custom Express + Postgres + JWT auth manually, this is a significant time saving. Before you start — install the right skill ------------------------------------------- claude skills add nextjs-app-router-pro This gives Claude Code pre-loaded context for the Next.js 14 + Supabase patterns. Sessions are significantly better with this skill installed. Part 1 — Schema design with Claude Code ----------------------------------------- Don't design your database schema in a UI — describe it to Claude Code and let it generate the SQL. > I'm building a SaaS project management tool. Users can create projects, invite team members, and create tasks within projects. Tasks have a status (todo, in_progress, done), a due date, and can be assigned to one team member. Design the database schema as PostgreSQL DDL. Include: table definitions with correct types and constraints, foreign key relationships, indexes for the most common queries (list tasks by project, list projects by user), and comments explaining non-obvious decisions. Review the output. Look for: - UUID vs bigint primary keys (UUID is safer for multi-tenant SaaS) - Missing indexes on foreign key columns (Postgres doesn't auto-index FKs) - Cascade behavior on deletes (usually you want cascade for child records, set null for assignments) Step 2 — Row Level Security (the most important part) ------------------------------------------------------ RLS is how Supabase enforces data isolation. Without it, any authenticated user can read any row. Claude Code writes RLS policies well, but you must verify them. > add Row Level Security policies for all tables. The rules are: users can only see projects they created OR projects they are a team member of (via a project_members table). Users can only see tasks that belong to projects they have access to. Users can only create tasks in projects they have access to. The generated policies will look like: create policy "users can view their projects" on projects for select using ( created_by = auth.uid() or exists ( select 1 from project_members where project_id = projects.id and user_id = auth.uid() ) ); Test these before shipping. The Supabase Dashboard has an RLS debugger — use it. The most common bug: a SELECT policy that's too permissive (missing conditions) or an INSERT policy that doesn't include enough context. > create a test scenario: a user with id '00000000-0000-0000-0000-000000000001' creates a project and a task. a different user with id '00000000-0000-0000-0000-000000000002' tries to select the project. write the SQL test queries I can run in Supabase's SQL editor to verify the RLS policies work correctly. Step 3 — TypeScript types from your schema ------------------------------------------ Supabase can generate TypeScript types from your schema. Run: npx supabase gen types typescript --project-id your-project-id > lib/supabase/types.ts Then tell Claude Code: > the file lib/supabase/types.ts contains auto-generated Supabase types. Use the Database type and the Row/Insert/Update helpers throughout the codebase. Never manually define types that correspond to database tables. This prevents the common mistake of hand-writing types that drift out of sync with the schema. Part 2 — Authentication patterns ---------------------------------- > set up Supabase Auth for a Next.js 14 App Router app. use the @supabase/ssr package (not the older auth-helpers package). create: lib/supabase/client.ts (browser client), lib/supabase/server.ts (server client using cookies), middleware.ts (session refresh on every request, protect /dashboard/* and /api/v1/* routes). The sign-in page should support GitHub OAuth and magic link. The critical detail Claude Code sometimes gets wrong: the @supabase/ssr package requires specific cookie handling for the server client. Verify that lib/supabase/server.ts uses cookies() from next/headers and has both get and set methods in the cookie handler. Part 3 — Real-time features ---------------------------- Supabase's real-time feature is one of the most underused capabilities. For a task management app: > add real-time task updates to the task list component. when another user updates a task status or adds a comment, the current user's view should update without a page refresh. use supabase.channel() with postgres_changes events. filter to only receive changes for the current project. Claude Code will generate a useEffect hook that subscribes to Postgres changes. Important: always unsubscribe in the cleanup function or you'll accumulate subscriptions on re-renders. Verify the generated code calls channel.unsubscribe() or supabase.removeChannel() in the useEffect cleanup. Part 4 — Edge Functions ------------------------ Supabase Edge Functions run on Deno at the edge. Use them for: webhook handlers, background jobs triggered by database events, and API routes that need to stay close to the database. > create a Supabase Edge Function called on-task-complete. it should be triggered when a task's status changes to 'done'. it should: 1) look up the task and project name, 2) find all project members, 3) send a notification email via Resend to each member except the one who completed the task. use the RESEND_API_KEY environment variable. Claude Code will create supabase/functions/on-task-complete/index.ts with a Deno-compatible TypeScript implementation. Key difference from Node.js: Edge Functions use Deno's fetch API (no node-fetch needed) and import from URLs for external modules. Deploy it: npx supabase functions deploy on-task-complete Set up the database webhook in the Supabase Dashboard: Database → Webhooks → Create a new webhook → table: tasks, event: UPDATE, Edge Function: on-task-complete. Part 5 — Storage ----------------- > add file attachment support to tasks. users can attach files up to 10MB per task. create a Supabase storage bucket called task-attachments with RLS (users can only access files belonging to tasks in their projects). add an upload function in lib/storage.ts and a file list component in components/task/attachments.tsx. For the RLS on storage, Claude Code will write storage policies. These use a slightly different syntax than table RLS — verify the generated policies use the storage.objects table and the auth.uid() function correctly. Production checklist --------------------- Before going live, ask Claude Code to audit your Supabase setup: > audit our Supabase integration for production readiness. check: 1) are all tables protected by RLS? 2) are there any security definer functions that bypass RLS unexpectedly? 3) are the API keys we expose client-side only the anon key (never the service_role key)? 4) do we handle auth session expiry gracefully? The service_role key should never appear in client-side code, .env.local committed to git, or anywhere except server-side environments. Claude Code will flag it if it finds it. Find more Supabase and full-stack skills at claudeskil.com/category/fullstack and claudeskil.com/category/backend.