web-nextjs

Web Platform: Next.js

The default web stack. Next.js App Router + Tailwind CSS + Supabase + Vercel.

Project Structure

Explain to the designer as:

"Your project is organized into folders. Think of each folder as a room with a specific purpose."

src/
  app/                    ← Pages (each folder = a page on your site)
    page.tsx              ← Home page (yourdomain.com/)
    layout.tsx            ← The wrapper around every page (nav, footer)
    about/
      page.tsx            ← About page (yourdomain.com/about)
    contact/
      page.tsx            ← Contact page (yourdomain.com/contact)
    dashboard/
      page.tsx            ← Dashboard (yourdomain.com/dashboard)
    login/
      page.tsx            ← Login page (yourdomain.com/login)
    actions.ts            ← Server actions (code that saves data)
  components/             ← Reusable pieces (navigation, footer, cards)
  utils/
    supabase/
      server.ts           ← Server-side database connection
      client.ts           ← Browser-side database connection
  middleware.ts           ← Page protection (bouncer for private pages)

public/                   ← Static files (images, favicon)
.env.local                ← Secret settings (database keys, API keys)

Key Conventions

Server vs Client Components

Don't explain "server components" and "client components" in those terms. Say:

• Default (server): "This code runs on the server before the page is sent to the visitor. Good for loading data from the database."
• 'use client': "This code runs in the visitor's browser. Needed when things are interactive — forms, buttons that do stuff, anything that changes on screen."

Rule of thumb:

• Page shows data from database → server component (default, no directive)
• Page has interactive elements (forms, modals, toggles) → add 'use client' at the top

Server Actions

Explain as: "Code that runs when someone submits a form."

'use server'

export async function doSomething(formData: FormData) {
  // This runs on the server, not in the visitor's browser
  // Safe to access the database here
}