Stripe Checkout Starter

Stop building payment flows from scratch.

A production-ready Next.js 16 template that handles Stripe payments so you can focus on what actually makes your product unique. One-time purchases, subscriptions, or both — configured in a single file.

---

The Problem

You've got a great idea for a SaaS, a digital product, or a paid tool. You pick Next.js. You pick Stripe. And then you spend the next two weeks:

• Reading Stripe docs at 2 AM trying to figure out webhook signatures
• Debugging why checkout.session.completed fires but your success page shows nothing
• Googling "stripe customer portal nextjs app router" for the 15th time
• Wondering if your webhook handler is actually secure or just looks secure
• Writing the same pricing card component you've written in every project since 2021

By the time payments work, your motivation is gone and your launch date is a memory.

We've been there. Multiple times. So we built this once — properly — and never looked back.

---

What You Get

One config file controls everything

// payments.config.ts — that's it, that's the whole decision
const config = {
  mode: "subscription",  // or "one-time" or "hybrid"
  customerPortal: { enabled: true },
  redirects: {
    success: "/checkout/success",
    cancel: "/checkout/cancel",
  },
}

Change mode and the entire app adapts — webhook events, UI components, checkout parameters. No hunting through 15 files to switch from subscriptions to one-time payments.

Not a tutorial project

This isn't a "build a Stripe integration in 10 minutes" blog post turned into a repo. This is what we actually use. That means:

• TypeScript strict mode — zero any, noUncheckedIndexedAccess enabled. Your IDE will catch bugs before your users do.
• ESLint with strictTypeChecked — zero warnings. Not "we disabled the rules that were annoying."
• Zod validation on every input — form data, URL params, webhook headers. If it comes from outside, it gets validated.
• Webhook signature verification — not optional, not a TODO comment. It's there and it works.
• Rate limiting — Upstash Redis sliding window on checkout creation. Because someone will try to spam your checkout endpoint.
• CSP + HSTS headers — with Stripe domains whitelisted. Not just "we'll add security headers later."

The boring stuff, done right

Nobody gets excited about error boundaries. But your users will notice when your app shows a blank white screen instead of a helpful error message.

• Error boundaries on every route segment — global, marketing, checkout
• Skeleton loading states on every page — not a spinner, actual layout-matching skeletons
• Custom 404 page — with navigation back to useful pages
• Inline error messages on checkout buttons — rate limit hit? Stripe error? The user sees exactly what happened

70 tests. Yes, for a template.

• Vitest unit tests covering validation schemas, pricing logic, Stripe helpers, and utility functions
• Playwright E2E tests covering the pricing page, checkout flow, success page, cancel page, and 404
• Not because we wanted a badge in the README (ok, partly), but because when you change the pricing config at 11 PM before launch, you want to know nothing broke

Webhook handlers ready to implement

Four event handlers with typed parameters, JSDoc comments, and TODO markers exactly where your logic goes:

• onCheckoutSessionCompleted — provision access, send confirmation
• onInvoicePaid — extend access on renewal
• onSubscriptionUpdated — handle plan changes, detect cancellation intent
• onSubscriptionDeleted — revoke access when the period ends

The customer ID is already extracted. The subscription ID is already extracted. You just add your database call.

---

The Stack

Next.js 16 (App Router) · TypeScript (strict) · Tailwind CSS 4 · shadcn/ui · Stripe SDK v20 · Zod · Vitest · Playwright

No experimental packages. No beta APIs. Nothing that will break in a month.

---

What's NOT included (on purpose)

• No database — Stripe is your source of truth. Add Prisma/Drizzle/whatever when you need it.
• No auth — Add NextAuth/Clerk/Lucia when you're ready. The webhook handlers have a clear spot for connecting auth to Stripe customers.
• No email service — The TODO comments tell you exactly where to send emails. Pick Resend, Postmark, whatever you like.

This is a payments template, not a full-stack boilerplate. It does one thing and does it well. You bring the rest.

---

How fast can you launch?

1. Clone the repo
2. Add your Stripe keys
3. Replace the placeholder price IDs with yours
4. Implement the webhook handlers (database writes, emails)
5. Deploy to Vercel

Steps 1-3 take about 5 minutes. Step 4 depends on your business logic, not on figuring out Stripe. Step 5 is one click.

---

"But I can just follow the Stripe docs..."

You absolutely can. And in about 20-30 hours you'll have something similar — if you remember to:

• Handle the case where session.customer is an expanded object, not a string
• Validate the returnPath parameter against open redirect attacks
• Mock the @t3-oss/env-nextjs module in tests because it validates env vars at import time
• Add overflow-visible to the pricing card so the "Most Popular" badge doesn't get clipped
• Use safeParse instead of parse for Zod validation in Server Actions so errors don't crash the server
• Check cancel_at_period_end in subscription updates, not just subscription deletions
• Rate limit by IP using x-forwarded-for with proper fallback for when there's no proxy

We already made every one of these mistakes so you don't have to.

---

What people usually ask

Can I use this for just one-time payments? Yes. Set mode: "one-time" and you're done. Subscription UI and webhook handlers are automatically disabled.

Do I need Upstash for rate limiting? No. Rate limiting is optional. Without the Upstash env vars, the app works fine — Stripe has its own API rate limits as a fallback.

Can I use pnpm/npm instead of bun? Yes. Delete bun.lock, run your preferred install command. Nothing in the code is bun-specific.

Is this a one-time purchase or a subscription? Ironic question for a Stripe checkout template, but: one-time purchase. Buy it, own it, use it forever.

Do you provide support? Yes. We actually use this template ourselves, so any bug you find is a bug we want fixed too.

---

Built by Peal.dev

We're Robert and Stefan. We build tools for developers who'd rather ship their product than fight with payment integrations.

This template exists because we got tired of rebuilding the same Stripe setup for every new project. Now we don't. And neither do you.