Build a Stripe Subscription SaaS with Next.js in a Weekend (Then Sell It)

npm install -g @anthropic-ai/claude-code

mkdir stripe-saas-starter && cd stripe-saas-starter
git init
claude

Build a Next.js 14 SaaS boilerplate using the App Router with the following stack:
- TypeScript throughout
- Tailwind CSS + shadcn/ui components
- NextAuth.js v5 (auth.js) with Google, GitHub, and credentials providers
- Prisma ORM with PostgreSQL
- Stripe for subscription billing (monthly + annual plans)
- Resend for transactional email
- Zod for validation

Create these routes and pages:
1. Landing page (/) with hero, features, and pricing section
2. Sign in (/auth/signin) and sign up (/auth/signup)
3. Dashboard (/dashboard) — protected, requires active subscription
4. Billing (/dashboard/billing) — manage subscription, upgrade, cancel
5. Settings (/dashboard/settings) — user profile settings
6. API webhook handler (/api/webhooks/stripe) for Stripe events

Prisma schema should include: User, Account (NextAuth), Session, Subscription, Price models.

The Stripe integration should handle these webhook events:
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.payment_failed

Add middleware that protects /dashboard/* routes — redirect to /pricing if no active subscription.

Include a .env.example with all required environment variables.

// app/api/webhooks/stripe/route.ts
import { headers } from "next/headers";
import { NextResponse } from "next/server";
import Stripe from "stripe";
import { stripe } from "@/lib/stripe";
import { prisma } from "@/lib/prisma";

const relevantEvents = new Set([
  "checkout.session.completed",
  "customer.subscription.created",
  "customer.subscription.updated",
  "customer.subscription.deleted",
  "invoice.payment_failed",
]);

export async function POST(req: Request) {
  const body = await req.text();
  const sig = headers().get("stripe-signature");
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(body, sig!, webhookSecret);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error";
    console.error(`Webhook signature verification failed: ${message}`);
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  if (!relevantEvents.has(event.type)) {
    return NextResponse.json({ received: true });
  }

  try {
    switch (event.type) {
      case "checkout.session.completed": {
        const session = event.data.object as Stripe.Checkout.Session;
        await handleCheckoutCompleted(session);
        break;
      }
      case "customer.subscription.created":
      case "customer.subscription.updated": {
        const subscription = event.data.object as Stripe.Subscription;
        await upsertSubscription(subscription);
        break;
      }
      case "customer.subscription.deleted": {
        const subscription = event.data.object as Stripe.Subscription;
        await prisma.subscription.update({
          where: { stripeSubscriptionId: subscription.id },
          data: { status: "canceled", canceledAt: new Date() },
        });
        break;
      }
      case "invoice.payment_failed": {
        const invoice = event.data.object as Stripe.Invoice;
        // Notify user via email, update subscription status
        await handlePaymentFailed(invoice);
        break;
      }
    }
  } catch (error) {
    console.error("Webhook handler error:", error);
    return NextResponse.json(
      { error: "Webhook handler failed" },
      { status: 500 }
    );
  }

  return NextResponse.json({ received: true });
}

async function handleCheckoutCompleted(session: Stripe.Checkout.Session) {
  const userId = session.metadata?.userId;
  if (!userId || !session.subscription) return;

  const subscription = await stripe.subscriptions.retrieve(
    session.subscription as string
  );

  await prisma.subscription.upsert({
    where: { userId },
    create: {
      userId,
      stripeCustomerId: session.customer as string,
      stripeSubscriptionId: subscription.id,
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
    },
    update: {
      stripeCustomerId: session.customer as string,
      stripeSubscriptionId: subscription.id,
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
    },
  });
}

async function upsertSubscription(subscription: Stripe.Subscription) {
  const existing = await prisma.subscription.findUnique({
    where: { stripeSubscriptionId: subscription.id },
  });

  if (!existing) return; // Only update subscriptions we know about

  await prisma.subscription.update({
    where: { stripeSubscriptionId: subscription.id },
    data: {
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
      cancelAtPeriodEnd: subscription.cancel_at_period_end,
    },
  });
}

async function handlePaymentFailed(invoice: Stripe.Invoice) {
  if (!invoice.subscription) return;

  await prisma.subscription.updateMany({
    where: { stripeSubscriptionId: invoice.subscription as string },
    data: { status: "past_due" },
  });

  // TODO: send payment failed email via Resend
}

// prisma/schema.prisma
model User {
  id            String   @id @default(cuid())
  name          String?
  email         String   @unique
  emailVerified DateTime?
  image         String?
  password      String?
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  accounts     Account[]
  sessions     Session[]
  subscription Subscription?
}

model Subscription {
  id                   String    @id @default(cuid())
  userId               String    @unique
  stripeCustomerId     String    @unique
  stripeSubscriptionId String    @unique
  stripePriceId        String
  status               String    // active, trialing, past_due, canceled, etc.
  currentPeriodEnd     DateTime
  cancelAtPeriodEnd    Boolean   @default(false)
  canceledAt           DateTime?
  createdAt            DateTime  @default(now())
  updatedAt            DateTime  @updatedAt

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
}

// app/api/checkout/route.ts
import { auth } from "@/auth";
import { stripe } from "@/lib/stripe";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const session = await auth();
  if (!session?.user?.id) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { priceId } = await req.json();

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: "subscription",
    payment_method_types: ["card"],
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing?canceled=true`,
    metadata: { userId: session.user.id },
    subscription_data: {
      metadata: { userId: session.user.id },
    },
    allow_promotion_codes: true,
  });

  return NextResponse.json({ url: checkoutSession.url });
}

// middleware.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  const session = await auth();

  // Redirect unauthenticated users to sign in
  if (!session?.user) {
    return NextResponse.redirect(new URL("/auth/signin", request.url));
  }

  // Check subscription for /dashboard/* routes
  if (request.nextUrl.pathname.startsWith("/dashboard")) {
    const sub = session.user.subscription;

    const isActive =
      sub?.status === "active" || sub?.status === "trialing";

    if (!isActive) {
      return NextResponse.redirect(new URL("/pricing", request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

> Review the project for production readiness. Check:
  - All TypeScript errors
  - Missing error boundaries
  - Any console.log left in the code
  - Missing loading states
  - Accessible form elements (labels, aria attributes)

> Add a comprehensive README with:
  - One-line description
  - Screenshot placeholder section
  - Prerequisites (Node 18+, PostgreSQL, Stripe account)
  - Step-by-step setup instructions (env vars, DB setup, Stripe webhooks)
  - Feature list with checkboxes
  - Tech stack section
  - Deploy to Vercel section

> Run ESLint and fix all warnings. Add Prettier config.
> Make sure npm run build passes cleanly.

# Start local Stripe webhook forwarding
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# In another terminal
npm run dev

gh repo create stripe-saas-starter --public --source=. --push

> Run a pre-listing quality audit. Check:
  - ESLint passes with no warnings
  - TypeScript compiles without errors (tsc --noEmit)
  - .env is in .gitignore, .env.example exists with all required vars
  - No hardcoded secrets or API keys in any file
  - README is complete with setup instructions
  - package.json has correct scripts (dev, build, test)
  - Dependencies are up to date (npm outdated)