ShipFast Documentation: Nuxt + Supabase Starter Kit

If you're searching for ShipFast documentation, you're really searching for one thing: a boilerplate whose docs explain how the plumbing actually works, not just how to clone a repo. This is that documentation, for BoiledPlate — an AI-native Nuxt + Supabase starter kit. It covers setup, billing, auth, deployment, and the edge cases that turn a five-minute demo into a three-week project.

Why Stack Choice Isn't Your Real Problem

Ask ten founders how to ship fast and you get ten stack arguments: Next vs Nuxt, Postgres vs a hosted DB, Stripe vs Paddle. Pick whatever you already know and the debate is over by lunch. The framework is not what slows you down.

What eats weeks is the integration work between services — webhooks, row-level security, refunds, consent flows. We call it plumbing. We wrote all of it, then kept a running log of every edge case it took to make it trustworthy. If you want the long version, read the stack is easy, the plumbing is the project.

BoiledPlate runs on Nuxt + Supabase + Stripe + Resend. It's a good stack — not because it's the hype stack, but because each piece has a clean division of labor once wired correctly. Here's what each piece actually demands.

Getting Started: Agent-Driven Setup in One Session

Most boilerplates hand you an empty project and a README. BoiledPlate's setup runs itself.

What happens when you run the interview

Your coding agent's first session interviews you — product name, languages, theme, billing model — then reshapes the entire codebase to your answers using deterministic patches: automated, repeatable code changes, not a wizard that overwrites your work.

Instant provisioning

The agent doesn't just write code. It provisions services: Stripe products and webhooks, a Supabase database with RLS, and Google sign-in. The plumbing nobody enjoys, done in one session instead of across a week of tab-switching between dashboards.

Manual wiring is the old way. You can still do it — that's what BoiledPlate Lite is for — but the point of the paid tier is skipping it.

The Plumbing Nobody Enjoys (And BoiledPlate Handles)

Webhook architecture

Stripe delivers webhooks at least once, which means your handler will get called twice for the same event sooner or later. Every handler is idempotent: repeated calls don't duplicate side effects. Stripe's own webhook best practices recommend exactly this. BoiledPlate ships it wired.

Stripe billing state as your source of truth

The checkout success page is a redirect, nothing more. It should never write billing state, because a user can close the tab, refresh, or never land on it at all. Subscription state lives in the webhook. We wrote a whole piece on why your success page should not touch your billing state.

Row-level security

Auth is the fast part. RLS is the part you forget. BoiledPlate ships row-level security enforced at query time in Supabase, so access rules live in the database, not scattered across middleware you hope you didn't skip.

Refund flows and subscription state

Refunds, cancellations, and downgrades all arrive as webhook events. Handling them — and reconciling them against your own tables — is the four-fifths of subscription work the demo never shows you. The full breakdown of Stripe subscriptions on Nuxt + Supabase walks the five decisions in order.

Authentication Done Right

Supabase auth ships with RLS policies out of the box, plus Google sign-in — the tedious OAuth callback and redirect wiring automated. Token refresh flows are included, so sessions don't expire silently mid-session. Multi-tenant patterns use RLS to scope every row to its owner, meaning a missed check in application code can't leak another tenant's data.

Billing That Survives Reality

Real billing is multi-plan, not flat-rate. BoiledPlate defines your plans in one place and drives checkout, webhooks, and access from that config.

If you sell to Germany, you may need a withdrawal-right waiver encoded into the pay button itself. We built this and documented it: encoding a German withdrawal waiver into Stripe Checkout. It's the kind of requirement you discover after launch if a starter doesn't handle it.

Handling webhook failures without data loss

Some webhook failures should throw so Stripe retries; some should never throw because retrying would double-deliver. The distinction matters when the webhook itself is how your product gets delivered — the GitHub invite IS the product is a real example from our own store.

Database Design for SaaS

BoiledPlate includes Supabase schema templates with RLS policies that actually protect data rather than decorate it. The hard cases are handled by design: deleted users, orphaned records, and tier downgrades. Migrations are structured to survive agent updates, so customizing your schema doesn't fight future releases.

AI Agent Consistency: AGENTS.md as Contract

Agents drift. Ask one to add a table today and another to add one next month, and you'll get two different data-access patterns unless something anchors them.

That anchor is AGENTS.md: a contract file documenting the one documented way to do data access, handle secrets, and follow conventions. Write conventions for the agent, not the next hire — here's why that framing changes what you write down. Because setup runs on deterministic patches, agent output stays consistent across sessions.

Updates Without Merge Hell

BoiledPlate Pro ships semantic, agent-readable release notes. Updates are opt-in, applied to your customized code without forcing a merge you'll dread. The goal is staying current without lock-in to the version you bought.

Internationalization from Day One

Four languages ship on day one, not as an afterthought. i18n is a tax you pay whenever you add it — the later you add it, the more strings you've hardcoded. Doing it at the start avoids that debt, and it pairs with multi-currency billing so language and pricing move together.

Blog and Content Infrastructure

The blog is prerendered Markdown: fast, SEO-friendly, and Git-native. You write posts in Markdown without touching component code. JSON-LD structured data, canonical URLs, and og: tags are configured per page.

SEO Out of the Box

BoiledPlate generates JSON-LD for organization and product schema, handles canonical URLs, and sets og:url and social sharing tags. Prerendered pages tend to outrank dynamic ones because crawlers get finished HTML, not a spinner. Sitemap and robots.txt follow sane conventions.

One caution from experience: get canonicals right. Ours once told Google its canonical URL was localhost:3000. That's the kind of bug a starter should prevent, and now does.

Transactional Email: Resend Integration

Receipts, confirmations, and billing alerts all need to send — and send exactly once. Resend is simple to send with, annoying to send idempotently. BoiledPlate ships a template system, handles failures gracefully, and lets you test flows without hitting production.

Deployment: Minutes, Not Hours

Deploy to Vercel or Netlify from GitHub. Environment variables for Stripe, Supabase, and Google are documented, database migrations run on deploy, and the stack is structured for fast cold starts.

Dashboard Theming: Preset or Custom

Pick a preset in the setup interview — Warm Studio, Clean SaaS, Midnight Pro, Sharp Enterprise — or describe your own and the agent maps it onto the codebase. Theming runs on CSS variables the agent can rewrite, with a persisted light/dark toggle and accessible color systems.

TypeScript Strict Mode End to End

Strict mode catches real bugs before runtime. Database types are generated from your schema, API contracts follow from types, and Stripe webhook payloads are typed on the client. One warning from the field: some packages break nuxt typecheck — we hit it with @vercel/analytics on Nuxt 4.

The Anti-Plumbing Stack: Why These Tools Work Together

Nuxt gives you file-based routing and server routes in one project. Supabase enforces RLS at query time instead of in middleware you might forget. Stripe gives you webhook delivery guarantees you can build on. Together they beat "microservices for everything" because there are fewer seams to wire — and seams are where plumbing lives.

Real-World Bugs and Lessons Learned

Documentation that only shows the happy path is marketing. Here are real fixes baked in:

JSON-LD hydration crashes: a page that returned 200 on the server and 500 in the browser, traced to source order.
Canonical redirect loops and localhost canonicals, covered above.
Peer dependency conflicts that break typecheck.
Webhook timeouts and signature verification failures, handled by idempotent, signature-verified handlers.

Free vs. Pro: Lite vs. Lifetime Updates

BoiledPlate Lite is free and MIT-licensed: clone it, wire the services manually, ship. Pro is €159 one-time with lifetime updates and instant delivery via GitHub — no subscription trap, one price, forever access.

Choose Lite if you enjoy the wiring or want to learn it. Choose Pro if you'd rather the agent provision everything in one session and save the weeks.

Tutorials and Common Pitfalls

The tutorials walk from a basic SaaS (auth + subscription) through multi-tier billing with seat limits, email confirmation flows, custom branding, and deploying with real secrets. Each maps to a pitfall the architecture prevents: RLS enforced at the database layer, idempotency keys against double charges, source-of-truth billing to stop state drift, refresh flows against silent token expiry, and build-time validation for missing i18n keys.

Extending BoiledPlate

Add custom tables while preserving RLS, write patches the agent can apply, add new Stripe products to existing subscriptions, and register custom webhook handlers for your domain — all following the AGENTS.md contract so future updates stay clean.

Glossary

Deterministic patches: automated, repeatable code changes that customize the starter to your answers.
Idempotent webhook: safely handles repeated calls without duplicating side effects.
Row-level security (RLS): access enforced at query time in the database.
Source of truth: Stripe webhooks for billing state, not client-side success pages.
Agent-readable conventions: the one documented way, written down so agents don't drift.

Ready to skip the plumbing? Start with BoiledPlate or browse the full blog for the edge cases behind every feature above.