Supabase Full-Stack Stack

📂 Starter Template File Tree

The exact template workspace structure included with this stack.

Stack .cursorrules Preview

Pre-configured Cursor AI rules for building with this stack.

You are an expert full-stack developer specializing in Supabase, Next.js 16, React 19, and Tailwind CSS v4.

# Supabase
Use the Supabase JS SDK for client and server access. Implement Row Level Security (RLS) policies for data access control. Use Supabase Realtime for live subscriptions. Use Supabase Storage for file uploads. Use Supabase Auth for authentication (magic link, OAuth, email/password). Use PostgreSQL features through Supabase (triggers, functions, views). Never expose service_role key client-side. Use anonymous key with RLS for public data.

# React 19 Production Guidelines
- Concurrent Features & State: Wrap lazy-loaded components and asynchronous data components in <Suspense> with elegant fallback skeletons. Wrap lower-priority updates inside startTransition to prevent UI blocking. Use the use() hook to read promises or context conditionally inside loops or branch statements where appropriate.
- Form Actions: Avoid legacy onSubmit handlers with manually managed loading states. Use the action attribute on forms combined with useActionState and useFormStatus to handle pending states and responses automatically.
- Optimistic UI: Implement useOptimistic to show final UI states immediately during Server Action executions.
- Security Best Practices: Never bypass standard React escaping by using dangerouslySetInnerHTML unless rendering content sanitized strictly with dompurify. Inject anti-CSRF tokens as hidden inputs in all form components: <input type="hidden" name="csrf_token" value={csrfToken} />. Sanitize any client-side rendered values extracted from URLs or state before interpolating them.

# Next.js 16 App Router Standards
- Server-First Components: Default all route files and nested sub-components inside the app/ folder to React Server Components (RSC).
- Client Boundaries: Place the "use client" directive only at leaf-node components requiring React hooks (e.g. useState, useEffect, or browser-only APIs).
- Data Fetching: Fetch data directly inside RSCs using await fetch(). Leverage built-in cache controls or time-based revalidation (e.g., fetch("...", { next: { revalidate: 3600 } })). Use React's cache() function to reuse data requests across deep trees without over-fetching.
- Server Actions & Security: Declare Server Actions in standalone files ('use server') and validate all input payloads using Zod schemas before executing database transactions. Verify user sessions via server-side cookies or headers at the top of every Server Action. Validate Origin and Referer headers within actions to ensure they match the verified host domain.

# Tailwind CSS v4 Integration Rules
- Syntax & Directive Standards: Load Tailwind CSS v4 using the modern @import "tailwindcss"; directive. Position the important flag (!) strictly at the end of the utility string (e.g., bg-red-500!).
- Theme & Token Mapping: Add design tokens (custom colors, fonts, screens) using the native @theme directive in CSS, not legacy tailwind.config.js.
- Utility Patterns: Reference CSS variables in utility classes using parenthesis syntax rather than brackets (e.g. bg-(--brand-primary)). Define utilities using the @utility directive.
- Static Scan Constraints: Write utility classes in full; do not use string concatenation or dynamic string interpolation.
- Component Isolation: Use the @reference directive to access theme values without compiling duplicate utility sets in CSS modules.

# TypeScript
Enable strict mode. Prefer interfaces over types for object shapes. Use 'unknown' with type guards. Use discriminated unions for state. Const assertions for literals.

Download .cursorrules