Tool-pair integration pattern
Supabase + Vercel deployment pattern
Supabase + Vercel is the dominant indie SaaS hosting stack. Supabase provides the database, auth, and storage; Vercel provides the Next.js hosting with preview deployments. The integration sits at environment variables and migration workflow.
Verified · editorial policy
Supabase owns
Database (Postgres), authentication, file storage, edge functions (server-side database access), row-level security policies.
Vercel owns (teardown →)
Next.js application hosting, edge network, preview-per-PR deployments, environment variable management, serverless function execution.
Integration shape
Connection by environment variables. Vercel-hosted Next.js code reads NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY for client-side; SUPABASE_SERVICE_ROLE_KEY for server-side admin operations.
Implementation steps
Step 1
Create the Supabase project and copy the keys
Supabase Dashboard → Project Settings → API. Copy URL, anon key, service role key. Service role key is admin; keep it server-only.
Gotcha: Service role key bypasses Row-Level Security. Never expose it in client-side code. Use environment variables marked as not-NEXT_PUBLIC.
Step 2
Configure Vercel environment variables
Vercel project Settings → Environment Variables. Three variables minimum: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (both client-safe), SUPABASE_SERVICE_ROLE_KEY (server-only).
Gotcha: Vercel has separate env-var contexts for Production, Preview, Development. Set the keys in all three contexts or your preview deploys break.
Step 3
Set up Supabase migrations in the repo
supabase init in the repo. supabase/migrations/ folder commits to git. Local development uses supabase start; production uses supabase db push or the Supabase Dashboard SQL editor.
Gotcha: Running migrations on production manually is the most common indie SaaS Supabase mistake. Always test in a staging Supabase project first.
Step 4
Use Vercel preview deploys with a separate Supabase project
Preview deploys against the production Supabase project produce real database mutations. Set up a separate Supabase project for preview environments; use Vercel's branch-specific env vars.
Gotcha: Preview deploys against production Supabase have caused real data corruption in indie SaaS. The separate-project pattern is non-optional for non-trivial apps.
Step 5
Set up auth callback URL for Vercel domain
Supabase Dashboard → Authentication → URL Configuration. Add your Vercel production URL and the preview-deploy URL pattern to the allowed redirect URLs.
Gotcha: Missing URLs in the allowed list make auth fail silently in production. Test the auth flow on the production URL before launch.
Common gotchas across the whole integration
- Supabase free tier pauses inactive projects after 7 days. For production, upgrade to the $25/mo Pro tier.
- Vercel's edge runtime is incompatible with Supabase's full client; use the server-side Supabase client in Route Handlers.
- Connection pooling matters at scale. Supabase's connection pooler (PgBouncer) is enabled by default; use the pooler URL in Vercel env, not the direct database URL.
- Vercel Function timeouts (10-30s on free tier) can interact with slow Supabase queries. Profile your queries and use indexes.
When NOT to build this integration
If you need a database with operational characteristics Supabase does not provide (sub-50ms read latency globally, complex multi-region, niche extensions), consider Neon + Vercel or direct Postgres. The Supabase + Vercel pattern is the indie SaaS default; not the only valid stack.
Frequently asked
- Should I use Supabase Auth or a separate auth provider?
- Supabase Auth for indie SaaS up to ~10k users; it covers email + social + magic link. Once you need enterprise features (SSO, SAML, complex RBAC), Clerk or WorkOS are stronger. Below that complexity, Supabase Auth is enough.
Other tool-pair integrations
See the stack this integration belongs to
Integration patterns assume the right stack underneath. Use the stack recommendations to pick the right tools first, then the integration to wire them together.