Next.js + Supabase + Supabase Auth + Paddle: A SaaS Stack for 2026

Next.js + Supabase + Supabase Auth + Paddle

Next.js with Supabase, Supabase Auth and Paddle is aimed at software with real revenue and real tax exposure. Paddle takes on global tax registration, dunning and business-to-business invoicing, while Supabase keeps the application data and the session. It suits a product past the experiment stage that is starting to sell into companies rather than only to individuals.

Next.js SupabaseSupabase AuthPaddle

Database

Supabase

Paddle's catalogue lives in their dashboard, so your Supabase schema should mirror price and product IDs rather than redefine them. Store the Paddle subscription ID, the current price ID and a resolved plan level, and treat that plan level as the only thing application code reads. Because Paddle supports invoiced business customers, expect an account or organization table sitting between users and subscriptions, since the person who pays is frequently not the person who signs in.

All database for Next.js → Supabase site →

Authentication

Supabase Auth

Supabase Auth handles individual identity, but a Paddle stack usually needs a layer above it. Model a membership table joining users to the paying account, and write row level security policies against membership rather than directly against the user ID. That way a finance contact who never logs in can hold the subscription while five colleagues get access. Supabase Auth invitations and email links cover onboarding those colleagues without adding a second identity vendor.

All authentication for Next.js → Supabase Auth site →

Payments

Paddle

Paddle earns its blended rate once tax jurisdictions multiply and failed charges start costing real money. Its recovery tooling retries and chases declines without you writing dunning logic, and it supports purchase orders and invoices that self-serve checkouts skip. You give up programmatic control of the catalogue, so pricing experiments mean dashboard work rather than a deployment, which is a fair trade at the stage where Paddle makes sense.

All payments for Next.js → Paddle site →

What to watch out for

Paddle approves merchants before you can sell, so this is not a Friday night launch. The deeper design friction is that its subscription model assumes the dashboard is authoritative, which sits uneasily beside a Supabase schema you version in migrations. Decide up front that Paddle owns pricing and Supabase owns access, and resist mirroring price amounts into Postgres where they will quietly go stale.

A CLAUDE.md for this stack

The rules that matter for this combination specifically, including who owns entitlement state. Adapt the commands to your repository before committing it.

CLAUDE.md

# CLAUDE.md

This project is a Next.js SaaS on Supabase, Supabase Auth and Paddle.

## Stack

- Framework: Next.js
- Database: Supabase
- Auth: Supabase Auth
- Payments: Paddle

## Boundaries

- Never edit a migration that has already run. Write a new one.
- Never hardcode Paddle price or product identifiers in components. They belong in config.
- Never trust a client-supplied user id. Read the session from Supabase Auth on the server.
- Treat webhook handlers as idempotent. The same event will arrive twice.

## Entitlements

- Paddle is the source of truth for what a customer paid for.
- The database mirrors that state; it never decides it.
- Any check for "can this user do X" reads the mirrored entitlement, not a live API call.

## Before you say a change is done

- The app builds.
- Tests pass.
- No secret, key or webhook signing secret appears in a committed file.

Generate a fuller version Agent setup for Next.js