Building an AI SaaS from Scratch with Next.js 15 (Complete Guide)

# Verify prerequisites
node --version          # Must be 20+
bun --version           # Alternative to Node — 1.1+
supabase --version      # Supabase CLI
stripe --version        # Stripe CLI

# Create Next.js 15 project
npx create-next-app@latest ai-saas \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias '@/*'

cd ai-saas

# Install all dependencies
npm install \
  @supabase/supabase-js \
  @supabase/ssr \
  stripe \
  @stripe/stripe-js \
  ai \
  @ai-sdk/openai \
  @ai-sdk/anthropic \
  zod \
  server-only \
  @upstash/redis \
  @upstash/ratelimit

# Initialize Supabase locally
supabase init
supabase start

import { z } from 'zod'

const envSchema = z.object({
  // Supabase — NEXT_PUBLIC_ vars are safe to expose to the client
  NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
  // Service role key bypasses RLS — server-only, never NEXT_PUBLIC_
  SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),

  // Stripe — publishable key is safe for client; secret key is server-only
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),

  // AI providers — server-only, never NEXT_PUBLIC_
  // OpenAI keys now support both sk- (legacy) and sk-proj- (project-scoped) formats
  OPENAI_API_KEY: z.string().min(1),
  ANTHROPIC_API_KEY: z.string().startsWith('sk-ant-').optional(),

  // Upstash Redis — for rate limiting
  UPSTASH_REDIS_REST_URL: z.string().url(),
  UPSTASH_REDIS_REST_TOKEN: z.string().min(1),

  // App
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
})

// Parse at module load time — build fails if any required variable is missing
export const env = envSchema.parse(process.env)

export type Env = z.infer<typeof envSchema>

-- Enable UUID extension
create extension if not exists "uuid-ossp";

-- ============================================================
-- USER MANAGEMENT
-- ============================================================

-- Profiles extends auth.users — one row per authenticated user
create table public.profiles (
  id uuid references auth.users on delete cascade primary key,
  email text not null,
  full_name text,
  avatar_url text,
  -- Stripe integration
  stripe_customer_id text unique,
  subscription_status text not null default 'free'
    check (subscription_status in ('free', 'active', 'past_due', 'cancelled', 'trialing')),
  -- Token quota enforcement
  token_usage_current_month integer not null default 0,
  token_limit_monthly integer not null default 10000,
  -- Timestamps
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

-- ============================================================
-- CONTENT
-- ============================================================

create table public.conversations (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references public.profiles(id) on delete cascade,
  title text not null default 'New Conversation',
  model text not null default 'gpt-4o-mini',
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

create table public.messages (
  id uuid primary key default gen_random_uuid(),
  conversation_id uuid not null references public.conversations(id) on delete cascade,
  user_id uuid not null references public.profiles(id) on delete cascade,
  role text not null check (role in ('user', 'assistant', 'system')),
  content text not null,
  created_at timestamptz not null default now()
);

-- ============================================================
-- USAGE TRACKING — feeds Stripe metered billing
-- ============================================================

create table public.usage_records (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references public.profiles(id) on delete cascade,
  conversation_id uuid references public.conversations(id) on delete set null,
  model text not null,
  prompt_tokens integer not null,
  completion_tokens integer not null,
  total_tokens integer generated always as (prompt_tokens + completion_tokens) stored,
  cost_usd numeric(10, 6) not null,
  -- Stripe meter event ID for idempotency
  stripe_meter_event_id text unique,
  created_at timestamptz not null default now()
);

-- ============================================================
-- STRIPE WEBHOOK IDEMPOTENCY
-- ============================================================

create table public.processed_webhook_events (
  stripe_event_id text primary key,
  processed_at timestamptz not null default now()
);

-- ============================================================
-- INDEXES
-- ============================================================

create index idx_conversations_user_created
  on public.conversations(user_id, created_at desc);

create index idx_messages_conversation_created
  on public.messages(conversation_id, created_at asc);

create index idx_messages_user
  on public.messages(user_id);

create index idx_usage_records_user_created
  on public.usage_records(user_id, created_at desc);

-- ============================================================
-- ROW LEVEL SECURITY
-- ============================================================

alter table public.profiles enable row level security;
alter table public.conversations enable row level security;
alter table public.messages enable row level security;
alter table public.usage_records enable row level security;
alter table public.processed_webhook_events enable row level security;

-- Profiles: users read and update their own profile only
create policy "users_select_own_profile"
  on public.profiles for select
  using (auth.uid() = id);

create policy "users_update_own_profile"
  on public.profiles for update
  using (auth.uid() = id);

-- Conversations: users manage their own conversations only
create policy "users_select_own_conversations"
  on public.conversations for select
  using (auth.uid() = user_id);

create policy "users_insert_own_conversations"
  on public.conversations for insert
  with check (auth.uid() = user_id);

create policy "users_update_own_conversations"
  on public.conversations for update
  using (auth.uid() = user_id);

create policy "users_delete_own_conversations"
  on public.conversations for delete
  using (auth.uid() = user_id);

-- Messages: users manage their own messages only
create policy "users_select_own_messages"
  on public.messages for select
  using (auth.uid() = user_id);

create policy "users_insert_own_messages"
  on public.messages for insert
  with check (auth.uid() = user_id);

-- Usage records: users read their own usage only
-- Inserts happen via service role in Route Handlers after AI calls
create policy "users_select_own_usage"
  on public.usage_records for select
  using (auth.uid() = user_id);

-- Webhook events: no direct user access — service role only
-- No policies needed: all access via service role bypasses RLS

-- ============================================================
-- TRIGGERS
-- ============================================================

-- Auto-create profile when a user signs up via Supabase Auth
create or replace function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = public
as $$
begin
  insert into public.profiles (id, email, full_name, avatar_url)
  values (
    new.id,
    new.email,
    new.raw_user_meta_data->>'full_name',
    new.raw_user_meta_data->>'avatar_url'
  );
  return new;
end;
$$;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

-- Auto-update updated_at timestamp
create or replace function public.handle_updated_at()
returns trigger
language plpgsql
as $$
begin
  new.updated_at = now();
  return new;
end;
$$;

create trigger profiles_updated_at
  before update on public.profiles
  for each row execute procedure public.handle_updated_at();

create trigger conversations_updated_at
  before update on public.conversations
  for each row execute procedure public.handle_updated_at();

import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'

// Routes that require authentication
const PROTECTED_ROUTES = ['/dashboard', '/chat', '/settings', '/billing']
// Routes that redirect authenticated users away
const AUTH_ROUTES = ['/login', '/signup']

export async function middleware(request: NextRequest) {
  let supabaseResponse = NextResponse.next({ request })

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll()
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value)
          )
          supabaseResponse = NextResponse.next({ request })
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options)
          )
        },
      },
    }
  )

  // CRITICAL: Always call getUser() — not getSession()
  // getUser() validates the token server-side and refreshes it if expired
  // getSession() returns cached data that may be stale
  const { data: { user } } = await supabase.auth.getUser()

  const pathname = request.nextUrl.pathname

  // Redirect unauthenticated users away from protected routes
  const isProtectedRoute = PROTECTED_ROUTES.some(route =>
    pathname.startsWith(route)
  )
  if (isProtectedRoute && !user) {
    const redirectUrl = new URL('/login', request.url)
    redirectUrl.searchParams.set('redirectTo', pathname)
    return NextResponse.redirect(redirectUrl)
  }

  // Redirect authenticated users away from auth pages
  const isAuthRoute = AUTH_ROUTES.some(route => pathname.startsWith(route))
  if (isAuthRoute && user) {
    return NextResponse.redirect(new URL('/dashboard', request.url))
  }

  // CRITICAL: Return supabaseResponse — not NextResponse.next()
  // supabaseResponse carries the refreshed session cookies
  return supabaseResponse
}

export const config = {
  matcher: [
    // Run middleware on all routes except static files and Next.js internals
    '/((?!_next/static|_next/image|favicon.ico|.*\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
}

import 'server-only'
import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'
import { env } from '@/lib/env'

const redis = new Redis({
  url: env.UPSTASH_REDIS_REST_URL,
  token: env.UPSTASH_REDIS_REST_TOKEN,
})

// Per-minute limit — prevents burst abuse
// 10 requests per minute per user, sliding window
export const minuteRatelimit = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(10, '1 m'),
  analytics: true,
  prefix: 'ratelimit:minute',
})

// Per-day limit — enforces daily request budget on free tier
// 100 requests per day per user, sliding window
export const dailyRatelimit = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(100, '24 h'),
  analytics: true,
  prefix: 'ratelimit:daily',
})

export interface RateLimitResult {
  success: boolean
  limit: number
  remaining: number
  reset: number // Unix timestamp when the window resets
  reason?: 'minute_limit' | 'daily_limit'
}

// Check both rate limits for a user
// Returns the most restrictive result
export async function checkRateLimit(userId: string): Promise<RateLimitResult> {
  const [minuteResult, dailyResult] = await Promise.all([
    minuteRatelimit.limit(userId),
    dailyRatelimit.limit(userId),
  ])

  // Per-minute limit hit
  if (!minuteResult.success) {
    return {
      success: false,
      limit: minuteResult.limit,
      remaining: minuteResult.remaining,
      reset: minuteResult.reset,
      reason: 'minute_limit',
    }
  }

  // Per-day limit hit
  if (!dailyResult.success) {
    return {
      success: false,
      limit: dailyResult.limit,
      remaining: dailyResult.remaining,
      reset: dailyResult.reset,
      reason: 'daily_limit',
    }
  }

  return {
    success: true,
    limit: dailyResult.limit,
    remaining: dailyResult.remaining,
    reset: dailyResult.reset,
  }
}

import 'server-only'
import { createOpenAI } from '@ai-sdk/openai'
import { createAnthropic } from '@ai-sdk/anthropic'
import { env } from '@/lib/env'

// AI clients — server-only, never imported in Client Components
// The server-only import above causes a build error if this file
// is transitively imported by any Client Component

export const openai = createOpenAI({
  apiKey: env.OPENAI_API_KEY,
})

export const anthropic = env.ANTHROPIC_API_KEY
  ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })
  : null

// Model selection with fallback
// Primary: OpenAI gpt-4o-mini (cost-effective for most queries)
// Fallback: Anthropic claude-3-haiku (if OpenAI is unavailable)
export type SupportedModel =
  | 'gpt-4o'
  | 'gpt-4o-mini'
  | 'claude-3-5-sonnet-latest'
  | 'claude-3-haiku-20240307'

export function getModel(modelId: SupportedModel) {
  if (modelId.startsWith('gpt-')) {
    return openai(modelId)
  }
  if (modelId.startsWith('claude-') && anthropic) {
    return anthropic(modelId)
  }
  // Default fallback
  return openai('gpt-4o-mini')
}

// Approximate cost calculation for usage recording
// Prices in USD per 1M tokens — update when provider pricing changes
const MODEL_COSTS: Record<SupportedModel, { input: number; output: number }> = {
  'gpt-4o': { input: 2.50, output: 10.00 },
  'gpt-4o-mini': { input: 0.15, output: 0.60 },
  'claude-3-5-sonnet-latest': { input: 3.00, output: 15.00 },
  'claude-3-haiku-20240307': { input: 0.25, output: 1.25 },
}

export function calculateCost(
  model: SupportedModel,
  promptTokens: number,
  completionTokens: number
): number {
  const costs = MODEL_COSTS[model] ?? MODEL_COSTS['gpt-4o-mini']
  return (
    (promptTokens * costs.input + completionTokens * costs.output) / 1_000_000
  )
}

import 'server-only'
import Stripe from 'stripe'
import { env } from '@/lib/env'

export const stripe = new Stripe(env.STRIPE_SECRET_KEY, {
  // Pin to a specific API version at project start
  // Update deliberately when Stripe releases breaking changes
  apiVersion: '2025-01-27.acacia',
  typescript: true,
})

export async function createCustomer(
  userId: string,
  email: string
): Promise<string> {
  const customer = await stripe.customers.create({
    email,
    metadata: { supabase_user_id: userId },
  })
  return customer.id
}

export async function createCheckoutSession(
  userId: string,
  email: string,
  stripeCustomerId: string | null,
  priceId: string
): Promise<string> {
  const session = await stripe.checkout.sessions.create({
    customer: stripeCustomerId ?? undefined,
    customer_email: stripeCustomerId ? undefined : email,
    client_reference_id: userId,
    line_items: [{ price: priceId, quantity: 1 }],
    mode: 'subscription',
    success_url: `${env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true`,
    cancel_url: `${env.NEXT_PUBLIC_APP_URL}/billing`,
    // Collect tax automatically — required for most jurisdictions
    automatic_tax: { enabled: true },
    // Allow promo codes for growth campaigns
    allow_promotion_codes: true,
  })

  if (!session.url) throw new Error('Failed to create checkout session URL')
  return session.url
}

export async function createBillingPortalSession(
  stripeCustomerId: string
): Promise<string> {
  const session = await stripe.billingPortal.sessions.create({
    customer: stripeCustomerId,
    return_url: `${env.NEXT_PUBLIC_APP_URL}/billing`,
  })
  return session.url
}

export async function recordMeterEvent(
  stripeCustomerId: string,
  totalTokens: number,
  idempotencyKey: string
): Promise<void> {
  await stripe.billing.meterEvents.create(
    {
      event_name: 'ai_tokens_used',
      payload: {
        stripe_customer_id: stripeCustomerId,
        value: totalTokens.toString(),
      },
    },
    // Stripe idempotency key prevents duplicate meter events
    { idempotencyKey }
  )
}

name: CI and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      # Type check — catches missing env vars at build time via Zod
      - run: npm run build
        env:
          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.PREVIEW_SUPABASE_URL }}
          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.PREVIEW_SUPABASE_ANON_KEY }}
          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.PREVIEW_SUPABASE_SERVICE_ROLE }}
          STRIPE_SECRET_KEY: ${{ secrets.PREVIEW_STRIPE_SECRET_KEY }}
          STRIPE_WEBHOOK_SECRET: ${{ secrets.PREVIEW_STRIPE_WEBHOOK_SECRET }}
          NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: ${{ secrets.PREVIEW_STRIPE_PUBLISHABLE_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          UPSTASH_REDIS_REST_URL: ${{ secrets.UPSTASH_REDIS_REST_URL }}
          UPSTASH_REDIS_REST_TOKEN: ${{ secrets.UPSTASH_REDIS_REST_TOKEN }}
          NEXT_PUBLIC_APP_URL: https://preview.your-app.com

      - run: npm run lint