How mohamed-4rarh/next-supabase-starter works
Project Type and Purpose
• This is a full-stack web application starter built with Next.js 15, Supabase (Auth + Postgres), and React Query.
• It provides reusable UI components (ShadCN + Tailwind), custom React Query hooks for data fetching/mutations, Supabase authentication and middleware, and form validation with Zod.
File Structure
• Top-level “app” directory: Next.js App Router with two primary route groups:
• (auth): login/register/confirm/error pages + auth actions + layout
• (dashboard): protected dashboard pages + layout
• “components”: shared UI primitives (buttons, cards, form controls) + a query‐provider wrapper and Auth state component
• “hooks”: use-client-fetch.ts & use-client-mutation.ts wrapping React Query + Supabase
• “lib”: auth-context.tsx (React Context for user state) + misc utilities
• “supabase”: client config, server helpers, and Next.js middleware integration
• Configuration files: next.config.ts, middleware.ts, Tailwind/PostCSS, ESLint, TypeScript
README for Additional Insights
• Confirms tech stack: Next.js 15, Supabase Auth & Database, React Query, ShadCN, Tailwind, Zod.
• Illustrates usage patterns: AuthContext provider, client fetch/mutate hooks, route protection, form validation.
a. Main Components
• Frontend (Next.js App):
– Pages & Layouts (app/(auth), app/(dashboard), app/page.tsx)
– Shared UI Library (components/ui)
– React Query & Auth Wrappers (components/query-provider.tsx, lib/auth-context.tsx)
– Custom Hooks (hooks/use-client-fetch & use-client-mutation)
• API Layer (Next.js Server + Supabase Client):
– Next.js Middleware (middleware.ts)
– Supabase client (supabase/client.ts) for authenticated calls
– Supabase server helpers (supabase/server.ts) for edge/server components
• Data Layer
– Supabase Postgres Database (tables for users, posts, etc.)
– Supabase Auth Service
• Utilities & Config
– Zod (schema validation, used in forms)
– Tailwind/PostCSS styling pipeline
– TypeScript types & ESLint
b. Relationships & Data Flows
• User Browser → Next.js App (Client Components & Pages)
• Client Components → React Query Hooks → Supabase Client → Supabase Auth/DB
• Next.js Middleware intercepts requests to protect dashboard routes and forward auth tokens
• AuthContext wraps the tree, reading supabase.auth.getUser() via React Query
• Mutations & Queries flow: UI → useClientFetch/useClientMutate → Supabase → React Query cache → UI
• Public assets served from /public
c. Architectural Patterns & Principles
• Folder-based routing (Next.js App Router)
• Separation of concerns: UI, Data Fetching, Auth, API integration
• React Context for cross-cutting concerns (authentication)
• Hook composition for reusable data logic
• Edge/Server components for SSR/edge middleware
d. Key Technologies & Libraries
• Next.js 15 (App Router, Middleware, Server/Client Components)
• Supabase (Auth + Postgres Database)
• React Query (caching, stale-while-revalidate)
• ShadCN UI + Tailwind CSS (design system)
• Zod (runtime data validation)
• TypeScript