Neon + Stack + Stripe SaaS Starter

Opinionated Next.js 16 starter for SaaS apps with authentication, billing, and database wiring already done. Stack powers auth flows, Stripe handles subscriptions (Managed Payments preview enabled), and Neon hosts the Postgres database. The todo list and "Pro" upsell are only placeholders to demonstrate user-scoped data—swap them for your product surface while keeping the pre-built plumbing.

What's included

• Auth: Hosted sign-up/sign-in/reset plus protected routes via Stack.
• Billing: Stripe Checkout + customer portal, idempotent webhooks, subscription state persisted in Neon.
• Data: Drizzle ORM schema + migrations for todos, subscriptions, and webhook event tracking.
• UI: Landing page + authenticated app shell with dark mode support.
• Deploy: Configs for Vercel, Netlify, and Render.
• Demo product: Free tier (5 todos) and Pro tier ($10/month, unlimited todos) to demonstrate tiered access.

Tech stack

• Framework: Next.js 16, React 19, TypeScript
• Styling: Tailwind CSS, Shadcn UI components
• Database: Neon (Postgres), Drizzle ORM
• Auth: Stack
• Payments: Stripe (Managed Payments API preview)

Requirements

• Node.js 18+
• Neon project + Postgres connection string (DATABASE_URL)
• Stack account with Project ID, publishable client key, and secret server key
• Stripe account (test mode is fine), product + recurring price, and webhook signing secret
• Stripe CLI (optional) for forwarding webhooks locally

Local setup

1. Copy environment variables

cp .env.example .env.local

2. Fill in values

• DATABASE_URL from Neon
• Stack: NEXT_PUBLIC_STACK_PROJECT_ID, NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, STACK_SECRET_SERVER_KEY
• Stripe: STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_PRO_MONTHLY_PRICE_ID
• NEXT_PUBLIC_APP_URL=http://localhost:3000
• For local webhooks, set STRIPE_WEBHOOK_SECRET from stripe listen --forward-to localhost:3000/api/webhooks/stripe

3. Install dependencies

npm install

4. Apply database migrations (requires DATABASE_URL)

npm run drizzle:migrate

5. Run the app

npm run dev

6. Create an account and try checkout on /account (Stripe test card: 4242 4242 4242 4242).

Scripts

• npm run dev — Start development server
• npm run build — Production build
• npm run stripe:listen — Forward Stripe webhooks locally
• npm run drizzle:generate — Generate new migrations
• npm run drizzle:migrate — Apply pending migrations
• npm run lint — Run ESLint
• npm run format — Format code with Prettier

Replacing the todo demo

• The todo UI lives in app/add-todo.tsx, app/todo-list.tsx, and app/actions.tsx; swap these for your product surface.
• The schema is defined in app/schema/schema.ts; adjust tables/columns and rerun npm run drizzle:migrate.
• Keep app/stack.tsx and app/stripe-actions.ts in place to preserve auth + billing wiring.
• Update every API key and price ID in .env.local (Neon DATABASE_URL, Stack keys, Stripe secret + publishable keys, STRIPE_PRO_MONTHLY_PRICE_ID, STRIPE_WEBHOOK_SECRET, and NEXT_PUBLIC_APP_URL) before launching or deploying.

Deployment and webhooks

1. Set environment variables on your host (Vercel/Netlify/Render):

DATABASE_URL=...                                    # Neon connection string
NEXT_PUBLIC_STACK_PROJECT_ID=...                    # Stack project ID
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=...        # Stack publishable key
STACK_SECRET_SERVER_KEY=...                         # Stack secret key
STRIPE_SECRET_KEY=sk_live_or_test...                # Stripe secret key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_or_test...
STRIPE_PRO_MONTHLY_PRICE_ID=price_...               # Your Pro plan price ID
STRIPE_WEBHOOK_SECRET=whsec_...                     # From Stripe webhook endpoint
NEXT_PUBLIC_APP_URL=https://your-domain.com

2. In Stripe → Developers → Webhooks, create an endpoint at /api/webhooks/stripe listening to:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed

Notes:

• You don’t need stripe listen in production; Stripe calls the deployed endpoint.
• Use separate webhook endpoints/secrets per environment if you want isolation.
• Managed Payments preview is enabled in lib/stripe.ts; ensure your Stripe account and products are eligible before using it in production.