Architecture & Stack

The recommended stack

For most web applications, we recommend this combination:

• Next.js - React framework with routing, API routes, and SSR
• Supabase - PostgreSQL database with authentication built in
• Tailwind CSS - Utility-first CSS that AI generates well
• Vercel - Deployment platform made for Next.js

This stack is popular, well-documented, and AI tools have extensive training data on it. You will get better suggestions and fewer errors.

Setting up Next.js

Create a new Next.js project with this command:

When prompted, select these options:

• TypeScript: Yes (helps AI understand your code better)
• ESLint: Yes
• Tailwind CSS: Yes
• src/ directory: Yes
• App Router: Yes

This creates a project structure AI tools understand well.

Project structure

A well-organized project is easier for AI to navigate. Here is the recommended structure:

my-app/
├── src/
│   ├── app/                 # Pages and routes
│   │   ├── page.tsx         # Home page
│   │   ├── layout.tsx       # Root layout
│   │   └── api/             # API routes
│   ├── components/          # Reusable components
│   │   ├── ui/              # Basic UI components
│   │   └── features/        # Feature-specific components
│   ├── lib/                 # Utilities and helpers
│   │   ├── supabase.ts      # Database client
│   │   └── utils.ts         # Helper functions
│   └── types/               # TypeScript types
├── public/                  # Static files
└── package.json

Setting up Supabase

1. Go to supabase.com and create a free account
2. Create a new project (pick a region close to your users)
3. Get your project URL and anon key from Settings > API
4. Install the client library:

Create a file to initialize the client:

// src/lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!

export const supabase = createClient(supabaseUrl, supabaseKey)

Database design basics

Before building, sketch out your database tables. For a task manager:

-- Users table (Supabase auth handles this)

-- Tasks table
CREATE TABLE tasks (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id),
  title TEXT NOT NULL,
  description TEXT,
  is_complete BOOLEAN DEFAULT false,
  due_date TIMESTAMP,
  created_at TIMESTAMP DEFAULT now()
);

You can create tables in the Supabase dashboard or ask AI to generate the SQL for you.

Environment variables

Store sensitive data in environment variables, not in code. Create a .env.local file:

# .env.local
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Add .env.local to your .gitignore file to keep secrets out of version control.

Checklist