Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-fullstack-supabase-nextjs

tpl-fullstack-supabase-nextjs

Verified

Template do pack (fullstack/07-supabase-nextjs.md). Orienta o agente em stacks fullstack e arquitetura ponta a ponta alinhado a esse contexto.

PROJECT: Next.js 15 + Supabase (Auth + DB + Storage + Realtime)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: fullstack/07-supabase-nextjs.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

  • Framework: Next.js 15 (App Router)
  • Backend: Supabase (Auth, PostgreSQL, Storage, Realtime)
  • Language: TypeScript 5.x (strict)
  • Client: @supabase/ssr (Next.js-specific helpers)
  • Styling: Tailwind CSS v3 + shadcn/ui
  • Type generation: supabase gen types typescript
  • Testing: Vitest + Playwright

PROJECT STRUCTURE

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── (auth)/
│   │   ├── login/page.tsx
│   │   └── signup/page.tsx
│   ├── (protected)/
│   │   └── dashboard/page.tsx
│   └── api/
│       └── auth/
│           └── callback/route.ts    # OAuth callback
├── lib/
│   ├── supabase/
│   │   ├── client.ts               # Browser Supabase client
│   │   ├── server.ts               # Server-side client (cookies)
│   │   └── middleware.ts           # Session refresh middleware
│   └── utils.ts
├── components/
│   ├── AuthButton.tsx
│   └── RealtimePosts.tsx           # Realtime subscription component
├── hooks/
│   └── useRealtimeSubscription.ts
└── types/
    └── database.types.ts           # Generated by supabase CLI
middleware.ts                       # Next.js middleware (session refresh)
supabase/
├── migrations/
│   └── 001_init.sql
└── seed.sql

ARCHITECTURE RULES

  1. Two Supabase clients — client.ts (browser, single instance) and server.ts (SSR, reads cookies); never mix them.
  2. Row Level Security is mandatory — every table has RLS enabled with explicit ENABLE ROW LEVEL SECURITY; deny-by-default.
  3. Server client for mutations in Server Actions/Route Handlers — always use server client for sensitive operations.
  4. Middleware refreshes sessions — middleware.ts calls supabase.auth.getUser() on every request to refresh tokens.
  5. Type-safe via database.types.ts — generated types used throughout; regenerate after every schema change.
  6. Storage buckets have policies — no bucket is public without intent; RLS-like bucket policies enforced.
  7. Realtime subscriptions only in Client Components — clean up with useEffect return function.

SUPABASE CLIENT SETUP

// src/lib/supabase/client.ts (singleton browser client)
import { createBrowserClient } from '@supabase/ssr'
import type { Database } from '~/types/database.types'

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

// src/lib/supabase/server.ts (server-side, reads/writes cookies)
import { createServerClient } from '@supabase/ssr'
import { cookies }            from 'next/headers'
import type { Database }      from '~/types/database.types'

export async function createClient() {
  const cookieStore = await cookies()
  return createServerClient<Database>(
    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)
          )
        },
      },
    }
  )
}

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

export async function middleware(request: NextRequest) {
  let supabaseResponse = 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: (c) => c.forEach(({ name, value, options }) => supabaseResponse.cookies.set(name, value, options)) } }
  )
  await supabase.auth.getUser()  // refreshes token automatically
  return supabaseResponse
}

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

ROW LEVEL SECURITY POLICIES

-- supabase/migrations/001_init.sql

-- Users can read all profiles; only own profile is updatable
CREATE TABLE profiles (
  id         UUID REFERENCES auth.users PRIMARY KEY,
  username   TEXT UNIQUE NOT NULL,
  avatar_url TEXT,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Public profiles are viewable by everyone"
  ON profiles FOR SELECT USING (true);

CREATE POLICY "Users can insert their own profile"
  ON profiles FOR INSERT WITH CHECK (auth.uid() = id);

CREATE POLICY "Users can update their own profile"
  ON profiles FOR UPDATE USING (auth.uid() = id);

-- Posts: public read; auth write own
CREATE TABLE posts (
  id         UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  title      TEXT NOT NULL,
  body       TEXT NOT NULL,
  author_id  UUID REFERENCES profiles(id) ON DELETE CASCADE NOT NULL,
  published  BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Published posts viewable by all"
  ON posts FOR SELECT USING (published = true OR author_id = auth.uid());

CREATE POLICY "Authors can insert posts"
  ON posts FOR INSERT WITH CHECK (auth.uid() = author_id);

CREATE POLICY "Authors can update their posts"
  ON posts FOR UPDATE USING (auth.uid() = author_id);

CREATE POLICY "Authors can delete their posts"
  ON posts FOR DELETE USING (auth.uid() = author_id);

REALTIME SUBSCRIPTION

// src/components/RealtimePosts.tsx
'use client'
import { useEffect, useState } from 'react'
import { createClient }        from '~/lib/supabase/client'
import type { Database }       from '~/types/database.types'

type Post = Database['public']['Tables']['posts']['Row']

export function RealtimePosts({ initialPosts }: { initialPosts: Post[] }) {
  const [posts, setPosts] = useState(initialPosts)
  const supabase = createClient()

  useEffect(() => {
    const channel = supabase
      .channel('posts-realtime')
      .on('postgres_changes',
        { event: 'INSERT', schema: 'public', table: 'posts', filter: 'published=eq.true' },
        (payload) => {
          setPosts(prev => [payload.new as Post, ...prev])
        }
      )
      .on('postgres_changes',
        { event: 'DELETE', schema: 'public', table: 'posts' },
        (payload) => {
          setPosts(prev => prev.filter(p => p.id !== payload.old.id))
        }
      )
      .subscribe()

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

  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

STORAGE BUCKET RULES

-- Storage: user avatars (private, own access only)
INSERT INTO storage.buckets (id, name, public) VALUES ('avatars', 'avatars', false);

CREATE POLICY "Avatar images are accessible by owner"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'avatars' AND auth.uid() = owner);

CREATE POLICY "Users can upload their own avatar"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'avatars' AND auth.uid() = owner AND (storage.foldername(name))[1] = auth.uid()::text);
// Uploading a file (Server Action)
async function uploadAvatar(file: File) {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) throw new Error('Not authenticated')

  const ext  = file.name.split('.').pop()
  const path = `${user.id}/avatar.${ext}`
  const { error } = await supabase.storage.from('avatars').upload(path, file, { upsert: true })
  if (error) throw error

  const { data } = supabase.storage.from('avatars').getPublicUrl(path)
  return data.publicUrl
}

ROUTING TABLE

Method / TriggerPath / EventAuthAction
GET/loginNoAuth.js sign-in page
GET/api/auth/callbackNoOAuth token exchange
GET/dashboardYesRSC with server client
POSTServer Action: createPostYesInsert via server client
POSTServer Action: uploadAvatarYesUpload to Storage
Realtimeposts INSERTNo (RLS)Push to client state
Realtimeposts DELETENo (RLS)Remove from client state
GET/storage/avatars/*Yes (RLS)Serve private avatar

QUALITY GATES

  • supabase gen types typescript --local > src/types/database.types.ts — in sync
  • tsc --noEmit — zero errors
  • Every table has ENABLE ROW LEVEL SECURITY + explicit policies
  • supabase db push — migration applied to remote without errors
  • Realtime components clean up subscriptions on unmount
  • Storage buckets are public: false unless intentionally public
  • playwright test — E2E auth flow passes
  • No anon key on server — use service role key only in trusted server contexts

FORBIDDEN

  • ❌ supabase.auth.getSession() for auth checks — use getUser() (validates JWT server-side)
  • ❌ Service role key exposed in client code or NEXT_PUBLIC_* env vars
  • ❌ Tables without RLS policies — never DISABLE ROW LEVEL SECURITY
  • ❌ Browser Supabase client in Server Components or Route Handlers
  • ❌ Direct supabase.from('users') on auth.users — use profiles table exposed via RLS
  • ❌ Realtime subscriptions opened in Server Components
  • ❌ POSTGREST_* bypass headers in client queries
  • ❌ public storage bucket without explicit policy review
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall