Installation

Get from a fresh clone to a running dev server.

Before you start

Node.js 18.18 or newer. Node 20 LTS is recommended.
A package manager: npm 9+, pnpm or yarn.
Accounts for Supabase, Stripe and Mailgun. Free and test tiers are fine.

Install dependencies

npm install

Create your env file

cp .env.example .env.local

Fill in the values. See Environment variables for what each one is and where to get it. The app validates env at startup, so a missing variable fails fast with a clear message.

Run the database migration

Apply supabase/migrations/0001_initial_schema.sql to your Supabase project, via the dashboard SQL editor or the Supabase CLI. It creates every table, RLS policy and trigger.

supabase db push

Start the dev server

npm run dev

Open http://localhost:3000. Without Mailgun credentials, magic-link sign-in URLs are printed to your terminal instead of emailed, so you can test auth locally before configuring email.

Optional services degrade gracefully

A fresh clone boots without Supabase, Stripe or Mailgun configured. The AI assistant shows only the providers whose keys are set, and auth falls back to Google OAuth plus terminal magic links. Wire each service when you need it.

Project structure at a glance

app/            Next.js App Router (pages, API routes, admin)
components/     UI component library (shadcn/ui based)
libs/           auth, supabase, stripe, mailer, security, config
models/         Zod schemas (user, subscription, payment, blogPost)
supabase/       SQL migrations
tests/          unit, integration and E2E tests

For the full tour, see Project structure.

Useful scripts

npm run dev          # dev server (Turbopack)
npm run build        # production build
npm run lint         # ESLint
npm run test:unit    # unit tests
npm run test:e2e     # Playwright E2E
npm run devtool      # interactive dev tool

Next steps

ConfigurationConnect Supabase, Stripe and Mailgun.FeaturesTour what is wired in.Project structureWhere everything lives.