Custom AI product and SaaS development

Next.js + Supabase for SaaS: what it gets you and what it doesn't

Next.js and Supabase together get you a working SaaS MVP fast: server-rendered frontend, Postgres database, authentication, file storage, and realtime updates, all wired together out of the box. What they don't get you, if you're building for South African customers, is billing that works in ZAR or a data setup that holds up under POPIA. Every popular tutorial and boilerplate defaults to Stripe and US assumptions, so a real SA build needs PayFast or Yoco bolted in, and a decision about where your data lives before you write a single frontend component.

This is the stack we use at Sagentics for client builds, and this article covers what it actually does, where the free tutorials stop being useful, and what breaks first when you take it from localhost to a paying South African customer base.

What Next.js + Supabase actually gives you

What Next.js handles: rendering, routing, edge functions

Next.js gives you server-side rendering, file-based routing, and API routes or edge functions for anything that needs to run server-side, like webhook handlers or auth callbacks. The App Router (stable since Next.js 13+) lets you mix server components that talk directly to Supabase with client components that need interactivity. For a SaaS dashboard this matters: your billing page can fetch data server-side with no loading spinner, while your realtime notification feed runs client-side.

What Supabase handles: Postgres, auth, storage, realtime, Row Level Security

Supabase is a managed Postgres database with an auth layer, file storage, realtime subscriptions, and edge functions layered on top. You get a real relational database (not a proprietary NoSQL store), which matters once your product needs joins, reporting, or anything beyond simple key-value lookups. Row Level Security (RLS) is the big one: instead of writing authorization logic in your API layer, you write Postgres policies that enforce who can see or edit which rows, directly at the database level.

Where Stripe or a billing provider fits in

Every Supabase SaaS tutorial you'll find assumes Stripe for billing, because Stripe has the best documented webhooks and the cleanest subscription API. That's fine if your customers are paying in USD from a US-registered entity. It falls apart the moment your business is South African, because Stripe doesn't support ZAR settlement or local card processing the way PayFast and Yoco do. This is the first place the standard tutorial stack quietly assumes a market you're not in.

Boilerplate vs custom build vs hiring a studio

What starter kits like Makerkit, ShipFast and Supastarter actually include

Most Next.js + Supabase boilerplates give you the same core: auth pages (sign up, login, password reset), a dashboard shell, Stripe billing already wired to webhooks, and basic RLS policies for a single-tenant or simple multi-tenant setup. Some throw in email templates, a marketing landing page, and dark mode. What they're really selling is the 40 to 60 hours of auth and billing plumbing you'd otherwise write yourself.

Free open-source starters vs paid boilerplates ($200-600 range)

Free starters (search GitHub for "supabase nextjs starter") give you the rough shape but usually skip production concerns: no rate limiting, thin RLS policies, no tested session refresh logic. Paid boilerplates in the $200 to $600 range (Makerkit, ShipFast, Supastarter) have generally been used in more production apps, so the auth edge cases and Stripe webhook handling are more battle-tested. Either way, you're buying US-market defaults.

Where boilerplates break down for South African businesses

The billing layer is Stripe-first, so you rip it out and rewire PayFast or Yoco, which means the webhook handlers, the subscription state machine, and the "what happens when a payment fails" logic all need rebuilding. None of the popular boilerplates ship with POPIA-aware defaults either: no data residency settings, no consent logging, no clear answer to "where does this personal information actually sit." You're not saving the time you paid for if half of what you bought needs to be replaced.

The South Africa gap: payments and compliance

Why Stripe alone doesn't work for ZAR billing

Stripe can technically charge a card in ZAR in some configurations, but you can't settle to a South African bank account without jumping through Stripe Atlas or a foreign entity setup, and even then you're paying cross-border fees on every transaction. For a South African business billing South African customers, that's an unnecessary tax on your margin from day one. Most local SaaS founders skip this entirely and reach for a local payment gateway instead.

Wiring PayFast or Yoco into a Supabase billing flow

PayFast and Yoco both support recurring billing, but neither has the plug-and-play Stripe SDK experience the tutorials assume. You're building your own subscription state table in Supabase, handling ITN (Instant Transaction Notification) callbacks from PayFast or webhook events from Yoco, and reconciling payment status manually against your subscriptions table. It's not hard, but it's not a five-minute Stripe Checkout redirect either. We've built PayFast and Yoco integrations into Supabase for multiple clients and the practical approach covers webhook handling, failed payment recovery, and subscription state reconciliation in detail.

POPIA and where your Supabase data actually lives

Supabase's default hosting regions are AWS-backed and typically sit outside South Africa (commonly in the EU or US, depending on project settings). POPIA doesn't ban this outright, but it does require you to know where personal information is stored, have a lawful basis for processing it, and be able to answer a data subject access request. Most Next.js + Supabase tutorials never mention this because it's not a US problem. For SaaS and automation products handling South African customer data, you need to deliberately choose a Supabase region and build consent logging into your schema from the start, since no boilerplate configures this by default.

Architecture decisions that bite you later

Row Level Security gotchas in multi-tenant setups

RLS is powerful but unforgiving. The most common mistake in multi-tenant Supabase apps is writing a policy that checks auth.uid() against a user_id column but forgetting that a service role key bypasses RLS entirely, meaning a leaked service key or a careless server-side query can expose every tenant's data at once. The second most common mistake is writing policies that work for SELECT but not INSERT or UPDATE, so a user can read their own data but accidentally overwrite someone else's row through a missing WITH CHECK clause. Test every policy against every operation, not just reads.

Auth session persistence with @supabase/ssr

If you've hit "auth session not persisting after refresh," it's almost always one of two things: you're using the old @supabase/auth-helpers package instead of the current @supabase/ssr package, or your cookie handling in middleware isn't refreshing the session token before it expires. The fix is to use @supabase/ssr's createServerClient in middleware, call getUser() (not getSession(), which doesn't validate against the server) on every request, and make sure your middleware matcher actually covers the routes where auth state matters. This one bug alone eats more debugging hours than almost anything else in the stack.

When pgvector replaces a separate vector database for AI features

If you're adding AI features like semantic search or RAG-based chat, you don't need Pinecone or a separate vector database. Supabase supports pgvector natively, so you store embeddings as a column type in the same Postgres database as everything else, query them with cosine similarity, and join them against your regular relational data in one SQL statement. For most SaaS-scale AI features (under a few million vectors) this performs fine and removes an entire piece of infrastructure you'd otherwise have to manage and pay for separately.

How long it actually takes and what it costs

Why auth alone eats 40-60 hours if built from scratch

Auth looks simple until you build it: sign up, email verification, login, password reset, session refresh, protected routes, role-based access, and handling edge cases like expired tokens or concurrent sessions. Doing this properly from scratch, including testing, realistically takes 40 to 60 hours even for an experienced developer. This is the single biggest reason boilerplates exist, and also the single biggest reason a bad boilerplate (untested auth flows) can cost you more time than it saves.

Realistic MVP timelines: solo dev vs agency vs boilerplate

A solo developer building from scratch with no boilerplate is realistically looking at 4 to 8 weeks for a functional MVP with billing. Using a well-tested paid boilerplate cuts that to 2 to 3 weeks, mostly spent on your actual product logic instead of auth and billing plumbing. Hiring a studio that's already solved the SA-specific problems (PayFast integration, POPIA-aware data setup, tested RLS policies) typically lands in the same 2 to 4 week range but with production-grade defaults from day one instead of defaults you'll need to rebuild later.

Build vs buy vs custom: the honest cost comparison

A paid boilerplate costs $200 to $600 once, plus your time replacing the Stripe layer with PayFast or Yoco and adding POPIA-aware data handling, which is easily another 30 to 50 hours of work. A studio build costs more upfront but includes that localisation from the start. The honest comparison isn't boilerplate price versus agency invoice, it's boilerplate price plus your hourly rate for the rework versus a fixed quote that already accounts for the SA-specific pieces.

When to use this stack and when not to

Good fit: indie SaaS, internal tools, AI apps needing pgvector

Next.js + Supabase is a strong choice for indie SaaS products, internal business tools, and AI-powered apps that need vector search alongside regular relational data. If you're a solo founder or small team building something with a straightforward data model, this stack gets you to a paying customer faster than almost anything else available, provided you plan for PayFast or Yoco from the start instead of retrofitting it.

Bad fit: heavy compliance, complex multi-tenant B2B, WhatsApp-first products

If you're building for a regulated industry (health, finance) with strict audit trail requirements, or a complex multi-tenant B2B product with deep permission hierarchies, Supabase's RLS model can become a maintenance burden fast, and you may be better served by a more explicit authorization layer. If your product is fundamentally a WhatsApp-first experience rather than a web dashboard, a different architecture entirely may fit better.

How Sagentics scopes a Next.js + Supabase build for SA clients

We start every build by scoping the actual data flow before touching code: where personal information sits, which billing provider fits the business model, and which parts of the tutorial stack need replacing versus which parts work as-is. For teams weighing whether to buy a boilerplate or hire a build, the key question is whether your business model (billing provider, compliance regime, data residency) matches what the boilerplate assumes, or whether you'll be spending 30-50 hours rebuilding its core assumptions. If it's the latter, a fixed-price studio build typically costs less in total time and money than paying for a boilerplate you'll need to heavily customise.

Common questions

What should a Next.js + Supabase boilerplate include? Auth (sign up, login, password reset, session handling), a dashboard shell, tested RLS policies for your tenancy model, and a billing integration. For South African use, check whether billing is Stripe-only, since you'll likely need to replace it with PayFast or Yoco, and confirm the RLS policies are tested against inserts and updates, not just reads.

Is Next.js + Supabase a good stack in 2026? Yes, for indie SaaS, internal tools, and AI-powered apps needing vector search. It's actively maintained, has a large community, and Supabase's pgvector support keeps it relevant for AI features. It's a weaker fit for heavily regulated industries or complex enterprise B2B permission models where a more explicit backend architecture may serve you better.

Is Supabase production ready for a South African SaaS business? Yes, technically, but you need to handle two things yourself: billing (Stripe doesn't settle in ZAR cleanly, so use PayFast or Yoco) and data residency for POPIA purposes, since default Supabase regions sit outside South Africa. Neither is a blocker, but neither is handled for you out of the box either.

How long does authentication take to build from scratch? Realistically 40 to 60 hours for a properly tested implementation covering sign up, verification, login, password reset, session refresh, and protected routes. This is why most developers reach for a boilerplate or a managed auth provider like Supabase Auth instead of writing it themselves from zero.

Should I use Stripe, PayFast, or Yoco for billing in a Supabase SaaS? For South African customers paying in ZAR, use PayFast or Yoco, since Stripe doesn't settle cleanly to South African bank accounts without a foreign entity setup. PayFast suits subscription billing with ITN webhooks; Yoco is often simpler for card-present or hybrid online/in-person businesses. Stripe still makes sense if your customer base is primarily international.

Is Next.js + Supabase POPIA compliant out of the box? No. POPIA compliance depends on where your data is stored, what consent and access controls you build, and how you handle data subject requests, none of which any boilerplate configures by default. You need to choose your Supabase region deliberately and build consent logging and access controls into your schema from the start.

Is Supabase or Firebase better for a new SaaS? Supabase gives you a real relational Postgres database with SQL, joins, and pgvector support, which suits most SaaS data models better than Firebase's NoSQL structure. Firebase can be faster for pure mobile-first realtime apps with simple data shapes. For SaaS products with reporting, billing state, and relational data, Supabase is generally the stronger fit.

How do I fix auth session not persisting after refresh in Supabase? Switch to the @supabase/ssr package instead of the deprecated auth-helpers, use createServerClient in your middleware, and call getUser() rather than getSession() on every request so the session is validated server-side. Also confirm your middleware matcher actually runs on the routes where you check auth state.

Should I buy a boilerplate or hire someone to build custom? Buy a boilerplate if your business model matches its assumptions closely (Stripe, US-style compliance, simple multi-tenancy) and you're comfortable doing the rework yourself. Hire a builder if you're in South Africa and want PayFast, Yoco, and POPIA-aware data handling done correctly the first time, since that rework often costs more in hours than the boilerplate saved.

Does Supabase need a separate vector database for AI features? No, for most SaaS-scale AI features. Supabase's pgvector extension stores embeddings alongside your relational data in the same Postgres database, letting you query similarity search and regular data together in one statement. A dedicated vector database only becomes worth the added infrastructure at very large scale, generally beyond a few million vectors.

If you're weighing this stack for your own build and want a second opinion before you write code or buy a boilerplate, drop us a message on WhatsApp and we'll talk through what your actual build needs.