Next.js + Supabase Starter App Rules

Apply these rules when implementing or modifying the starter app. Names for routes, components, and hooks are flexible—use clear, consistent names and document choices. The starter should be well-documented, easy to set up, and include essential features for a modern web app with authentication.

---

1. Next.js

• Version: Use the latest Next.js; follow Next.js 13+ App Router conventions.
• App Router only: Use the

  app/

  directory; do not use

  pages/

  .
• TypeScript: Use TypeScript throughout; no

  any

  without justification. Use explicit semicolons at the end of statements in

  .ts

  and

  .tsx

  files.
• Project structure: Organize with

  app/

  ,

  components/

  ,

  lib/

  , etc. Document structure and conventions in README.
• Styling: Use Tailwind CSS primarily, and plain CSS if needed.
• Mobile-first: All layout and typography must be mobile-first. In Tailwind, base (unprefixed) classes define styles for the smallest viewport (mobile). Use

  sm:

  ,

  md:

  ,

  lg:

  only to add or override for larger screens. Do not use base classes for desktop and then scale down with breakpoints—design for mobile first, then enhance upward (e.g. base

  text-sm

  /

  p-4

  , then

  md:text-base

  /

  md:p-6

  ). Use touch-friendly minimum sizes on mobile (e.g.

  min-h-[2.75rem]

  for buttons/links) and relax with

  sm:min-h-0

  or

  md:

  when appropriate. Page content should use

  min-h-[calc(100vh-3.5rem)]

  (or similar) to account for the header so vertical centering and scroll behavior are correct.
• Middleware: Use Next.js middleware for Supabase token refresh; implement the refresh logic in

  proxy.ts

  and use it from

  middleware.ts

  (see Supabase section).
• Server vs client: Prefer Server Components by default; add

  'use client'

  only where needed (e.g. forms, auth state in UI). Colocate route-specific components in route folders when it makes sense.
• UX: Use

  loading.tsx

  and

  error.tsx

  in route segments for loading and error states where appropriate.

---

2. Supabase Integration

• CLI and client: Install and configure Supabase CLI and client libraries; use

  @supabase/ssr

  for SSR-safe usage.
• Local dev: Set up Supabase for local development; run via

  npx supabase start

  ; setup script configures and documents this.
• Two client utilities: Provide separate helpers for server and client components (e.g.

  createServerClient

  ,

  createBrowserClient

  in

  lib/supabase/

  ) using

  @supabase/ssr

  .
• Middleware: Configure Next.js middleware for token refresh using

  proxy.ts

  : put the session refresh / proxy logic in

  proxy.ts

  and invoke it from

  middleware.ts

  so the session is updated on each request.
• Environment: Require

  NEXT_PUBLIC_SUPABASE_URL

  and

  NEXT_PUBLIC_SUPABASE_ANON_KEY

  in

  .env.local

  ; document in README. Never expose the service_role key in client or frontend code; use only the anon key in the app.
• Storage (e.g. avatars): If using Supabase Storage, create a bucket and set RLS so users can read/update only their own objects (e.g. by path or user id).

---

3. Database and Migrations

• No manual SQL: All schema changes go through migration files only.
• Declarative schemas: Define tables in

  supabase/schemas/

  (e.g.

  supabase/schemas/profiles.sql

  ). Generate migrations with:

  npx supabase db diff -f <migration_name>
  

• Profiles table:
  • Primary key:

    id

    referencing

    auth.users(id)

    .
  • Include

    updated_at

    with a trigger that sets it on row update.
  • Define in declarative schema; add trigger and RLS in migrations.
• Automatic profile creation: Use a PostgreSQL trigger that:
  • Fires AFTER INSERT on

    auth.users

    .
  • Reads the new user’s email (and id) from the inserted row.
  • Inserts one row into

    profiles

    with that

    id

    and email. Trigger and function live in a migration file.

---

4. Row Level Security (RLS)

• Enable RLS on

  profiles

  .
• Policies (use

  auth.uid()

  ):
  • SELECT: User can read only their own profile.
  • UPDATE: User can update only their own profile.
  • INSERT: User can insert only their own profile (backup to trigger).
• Ensure users cannot read or modify other users’ profiles.

---

5. Authentication

• Implement: Sign up, sign in, sign out.
• Protected routes: Redirect unauthenticated users to login (e.g. from dashboard/profile).
• State: Handle auth state correctly in both server and client components.
• Patterns: Use consistent patterns—e.g. a

  useAuth()

  (or similar) hook for client components and server-side helpers (e.g.

  getUser()

  ) for server components. Document these in README.
• Errors: Handle auth errors (invalid credentials, network, etc.) and show clear messages.

---

6. Example Pages and Routes

Route names are flexible (e.g.

/auth/login

,

/account

); keep them logical and consistent.

• Home (

  /

  ): Welcome, auth status, link to login/signup when logged out, link to dashboard when logged in.
• Login: Email/password form, error handling, redirect to dashboard on success.
• Signup: Email/password form, error handling, redirect to dashboard on success.
• Dashboard (protected): Require auth; show profile summary and link to profile; sign out.
• Profile (protected): Require auth; show profile; form to update (e.g.

  full_name

  and any other profile fields); avatar upload that allows selecting/uploading an image, stores it (e.g. Supabase Storage), updates

  avatar_url

  in

  profiles

  , displays the avatar, and includes a save/update button; handle upload and validation errors.

---

7. Setup Script

• Purpose: One command to install deps, start Supabase, write env, run migrations. Implement as

  setup.sh

  ,

  setup.js

  , or use a tool like zx for cross-platform support; ensure it works reliably and handles edge cases.
• Assumptions: Supabase is already initialized (

  supabase/

  with migrations and schemas exists). Do not assume a clean machine beyond that.
• Idempotent: Safe to run multiple times. If

  .env.local

  exists, either skip or update it. If Supabase is already running, handle gracefully (e.g. skip start or detect and continue).
• Steps (in order):

  1. npm install

  2. npx supabase start

     (or detect already running)
  3. Extract Supabase URL and anon key from

     supabase start

     output
  4. Create or update

     .env.local

     with

     NEXT_PUBLIC_SUPABASE_URL

     and

     NEXT_PUBLIC_SUPABASE_ANON_KEY

  5. Run migrations:

     npx supabase db reset

     or

     npx supabase migration up

  6. Print clear output showing what was done and next steps
• Errors: Provide helpful error messages if something goes wrong. In README, include instructions on how to run the script and troubleshoot.

---

8. Code Organization and Documentation

• Explicit structure: Decide where things live (e.g.

  components/

  ,

  components/ui/

  ,

  lib/hooks/

  ,

  lib/utils/

  ) and document in README so anyone using the starter understands structure and conventions.
• Reusable components: Store shared UI (buttons, forms, etc.) in a documented location.
• Hooks and utils: Keep custom hooks (e.g. auth) and utility functions in consistent locations; document naming and usage.
• README must include: Project description and purpose; prerequisites (Node.js version, Docker for Supabase, etc.); quick start (how to run the setup script); manual setup (step-by-step if someone prefers); project structure; how to use this starter for new projects; environment variables; database schema overview; authentication flow; deployment instructions; GitHub Actions setup and configuration; troubleshooting section.

---

9. Testing

• Framework: Use a unit test framework (e.g. Jest, Vitest).
• Coverage: Include at least a few examples for:
  • React components
  • Utility functions
  • Auth-related code
• README: How to run tests and how to add new tests.

---

10. Deployment and CI/CD

• Deployment docs: Document how to deploy to production (e.g. Vercel, Netlify): steps to set up the production Supabase project; how to configure environment variables in the deployment platform; how to link the production database; any platform-specific considerations (e.g. on Vercel: set env vars in project settings, use production Supabase URL/anon key, do not commit

  .env.local

  ).
• Vercel: If deploying on Vercel, use the dashboard for env vars, connect the repo, and ensure

  NEXT_PUBLIC_*

  and Supabase keys are set. Middleware runs on the Edge runtime by default.
• GitHub Actions: Create a workflow that triggers on deployment or push to main/production branch; connects to the production Supabase instance; runs pending migrations via Supabase CLI; uses GitHub Secrets for sensitive credentials; handles errors with clear feedback. Document in README how to set up and configure the workflow and secrets.

---

11. General

• Error handling: Include proper error handling for authentication and database operations; avoid silent failures.
• Comments: Add comments in code where logic or intent is non-obvious.
• Naming: Use clear, consistent names for routes, components, hooks, and functions; document in README when choices affect how others use the starter.

12. Submission Checklist

• Remove

  node_modules

  before submitting. Zip the project folder; do not delete the

  supabase/

  directory (migrations and schemas must remain).
• Ensure the setup script is included and executable.
• Verify README is comprehensive and clear.