Next.js + Supabase Interview Starter

A ready-to-go starter repo for live coding exercises. Comes with a Next.js app, a locally running Supabase instance, a sample database schema, seed data, and TypeScript types -- all wired up and working.

Prerequisites

Before you begin, make sure you have:

• Node.js >= 18 (download)
• Docker Desktop running (download)

The Supabase CLI is included as a dev dependency -- no global install required.

Quick Start

# 1. Clone the repo
git clone <repo-url> && cd nextjs-supabase-starter

# 2. Run the setup script (installs deps, starts Supabase, seeds the DB)
npm run setup

# 3. Start the app
npm run dev

Then open http://localhost:3000 in your browser.

First run? npm run setup will pull Docker images for Supabase, which can take 1-2 minutes. Subsequent starts are fast.

What's Included

Layer	Details
Framework	Next.js 16 (App Router, TypeScript, Tailwind CSS)
Backend	Supabase (local via Docker -- Postgres, REST API, Studio)
Schema	todos table with RLS enabled (permissive policy)
Seed Data	5 sample todos pre-loaded
Types	Auto-generated TypeScript types for the database
UI	Simple todo list with add, toggle, and delete functionality

Project Structure

nextjs-supabase-starter/
├── scripts/
│   └── setup.sh              # One-command setup script
├── supabase/
│   ├── config.toml            # Supabase local config
│   ├── migrations/
│   │   └── 20250206000000_create_todos.sql
│   └── seed.sql               # Sample data
├── src/
│   ├── app/
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Home page (server component)
│   │   ├── globals.css        # Global styles
│   │   └── components/
│   │       └── todo-list.tsx  # Interactive todo list (client component)
│   └── lib/
│       └── supabase/
│           ├── client.ts      # Browser Supabase client
│           ├── server.ts      # Server Supabase client
│           └── database.types.ts  # Generated DB types
├── .env.local                 # Local Supabase credentials (pre-filled)
├── .env.local.example         # Reference for env vars
├── package.json
└── README.md

Useful Commands

Command	Description
npm run setup	Full setup (install, start Supabase, seed DB)
npm run dev	Start the Next.js dev server
npm run supabase:start	Start Supabase containers
npm run supabase:stop	Stop Supabase containers
npm run supabase:status	Show Supabase service URLs and status
npm run db:reset	Reset DB (re-run migrations + seed)
npm run db:types	Regenerate TypeScript types from the DB
npm run build	Production build
npm run lint	Run ESLint

Supabase Studio

Once Supabase is running, open http://localhost:54323 to browse your database, view tables, run SQL queries, and more.

Candidate Instructions

Your interviewer will provide instructions for the coding exercise.

Troubleshooting

Docker is not running

ERROR: Docker is not running. Please start Docker Desktop and try again.

Start Docker Desktop and wait for it to be ready, then re-run npm run setup.

Port conflicts

If ports 54321-54327 are in use, another Supabase instance may be running. Stop it with:

npm run supabase:stop

Supabase won't start

Try resetting the Supabase containers:

npx supabase stop --no-backup
npm run supabase:start
npm run db:reset

"Error connecting to Supabase" in the app

Make sure Supabase is running (npm run supabase:status) and the database has been seeded (npm run db:reset).

Regenerate types after schema changes

After modifying migrations or the database schema:

npm run db:reset
npm run db:types