Production Deployment Checklist for Next.js Supabase SaaS

Deploy your MakerKit Next.js Supabase Turbo application to production by completing this checklist in order. This guide covers Supabase configuration, authentication setup, billing webhooks, and hosting deployment for Next.js 16 with React 19.

Quick Reference

Pre-Deployment Requirements

Before starting, ensure you have accounts and API keys for:

• Supabase: Database, authentication, and storage
• Billing provider: Stripe or Lemon Squeezy with API keys and webhook secrets
• Email provider: Resend, SendGrid, Mailgun, or another SMTP service
• Hosting provider: Vercel, Cloudflare, or a VPS

Step 1: Create and Link Supabase Project

Create a new project in the Supabase Dashboard. Save your database password securely as you will need it for the CLI.

Link your local project to the remote Supabase instance:

pnpm --filter web supabase login
pnpm --filter web supabase link

The CLI will prompt you to select your project and enter the database password.

Verification: Run supabase projects list to confirm the link.

Step 2: Push Database Migrations

Push MakerKit's database schema to your production Supabase instance:

pnpm --filter web supabase db push

Review the migrations when prompted. You should see the core MakerKit tables (accounts, subscriptions, invitations, etc.).

Verification: Check the Supabase Dashboard Table Editor to confirm tables exist.

Step 3: Configure Authentication URLs

In the Supabase Dashboard, navigate to Authentication > URL Configuration.

Set these values:

Important: The redirect URL must include the ** wildcard to handle all callback paths.

For detailed instructions, see the Authentication Configuration guide.

Step 4: Set Up OAuth Providers (Optional)

If you want social login (Google, GitHub, etc.), configure providers in Authentication > Providers in the Supabase Dashboard.

Each provider requires:

1. Creating an OAuth app in the provider's developer console
2. Copying the Client ID and Secret to Supabase
3. Setting the callback URL from Supabase in the provider's console

MakerKit automatically displays configured providers in the login UI. No code changes needed.

For Google Auth setup, see the Supabase Google Auth guide.

Step 5: Update Authentication Email Templates

MakerKit provides custom email templates that fix PKCE flow issues when users click email links from different browsers or devices.

Update your email templates in Authentication > Email Templates in the Supabase Dashboard. Use the templates from apps/web/supabase/templates/ as your starting point.

For detailed instructions, see the Authentication Emails guide.

Step 6: Deploy Your Application

Choose your deployment platform:

Which platform should I choose?

Use Vercel when: You want the simplest setup with preview deployments, need commercial use rights (Pro tier), or are new to deployment. Works out of the box with MakerKit.

Use Cloudflare when: You need zero cold starts for global users, want lower costs at scale, or are comfortable making Edge runtime configuration changes.

Use VPS when: You need full infrastructure control, want predictable costs regardless of traffic, or have compliance requirements for data location.

If unsure: Start with Vercel. You can migrate later since MakerKit supports all platforms.

Expected: Your first deployment will likely fail if you haven't set all environment variables. This is normal. Continue to the next step.

Step 7: Set Environment Variables

Generate your production environment variables using the built-in tool:

pnpm turbo gen env

This interactive command creates a .env.local file at turbo/generators/templates/env/.env.local with all required variables.

Copy these variables to your hosting provider's environment settings.

Required variables include:

• NEXT_PUBLIC_SITE_URL: Your production URL
• NEXT_PUBLIC_SUPABASE_URL: From Supabase Dashboard > Settings > API
• NEXT_PUBLIC_SUPABASE_PUBLIC_KEY: Supabase anon key
• SUPABASE_SECRET_KEY: Supabase service role key
• Billing provider keys (Stripe or Lemon Squeezy)
• Email provider configuration

For the complete list, see Environment Variables.

After setting variables, redeploy your application.

Step 8: Configure Database Webhooks

MakerKit uses database webhooks to handle events like subscription cancellations when accounts are deleted.

Generate a Webhook Secret

Create a strong, random secret for SUPABASE_DB_WEBHOOK_SECRET:

openssl rand -base64 32

Add this to your environment variables on your hosting provider.

Create the Webhook in Supabase

In Supabase Dashboard, go to Database > Webhooks:

1. Click Enable Webhooks if not already enabled
2. Click Create a new hook
3. Configure:
   • Table: public.subscriptions
   • Events: DELETE
   • URL: https://yourdomain.com/api/db/webhook
   • Headers: Add X-Supabase-Event-Signature with your webhook secret value
   • Timeout: 5000

For detailed webhook setup, see the Supabase Deployment guide.

Step 9: Configure Email Service (SMTP)

Supabase's built-in email service has low rate limits and poor deliverability. Configure a real SMTP provider for production.

In Your Environment Variables

Set the mailer configuration:

MAILER_PROVIDER=resend  # or nodemailer
EMAIL_SENDER=noreply@yourdomain.com
RESEND_API_KEY=re_xxxxx  # if using Resend

In Supabase Dashboard

Navigate to Project Settings > Authentication > SMTP Settings and configure your provider's SMTP credentials.

Recommended providers: Resend, SendGrid, Mailgun

Step 10: Configure Billing Provider

Stripe Setup

1. Create products and prices in the Stripe Dashboard
2. Set environment variables:
   NEXT_PUBLIC_BILLING_PROVIDER=stripe
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxx
   STRIPE_SECRET_KEY=sk_live_xxx
   STRIPE_WEBHOOK_SECRET=whsec_xxx

3. Create a webhook endpoint in Stripe pointing to https://yourdomain.com/api/billing/webhook
4. Select events: checkout.session.completed, customer.subscription.*, invoice.*

Lemon Squeezy Setup

1. Create products in Lemon Squeezy
2. Set environment variables:
   NEXT_PUBLIC_BILLING_PROVIDER=lemon-squeezy
   LEMON_SQUEEZY_SECRET_KEY=xxx
   LEMON_SQUEEZY_STORE_ID=xxx
   LEMON_SQUEEZY_SIGNING_SECRET=xxx

3. Configure webhooks in Lemon Squeezy pointing to https://yourdomain.com/api/billing/webhook

Post-Deployment Tasks

After completing the main deployment:

Optional: Clear Expired OTPs

MakerKit stores one-time passwords for various flows. Clean these up periodically by running:

SELECT kit.cleanup_expired_nonces();

You can run this manually from the Supabase SQL Editor or set up a pg_cron job to run it automatically.

Troubleshooting

Build fails with missing environment variables

MakerKit validates environment variables at build time using Zod. Check the build logs to see which variables are missing, then add them to your hosting provider.

Authentication redirects fail

Ensure your Site URL and Redirect URLs in Supabase exactly match your domain, including www if you use it.

Webhooks not received

1. Verify the URL is publicly accessible (test in incognito mode)
2. Check the X-Supabase-Event-Signature header matches your secret
3. Review webhook logs in Supabase Dashboard > Database > Webhooks

Emails not sending

1. Confirm SMTP settings in both environment variables and Supabase Dashboard
2. Check your email provider's logs for delivery issues
3. Verify your domain's DNS records (SPF, DKIM) are configured

Next Steps

• Supabase Production Setup: Configure your Supabase project with migrations, RLS policies, and webhooks
• Vercel Deployment: Deploy to Vercel with automatic CI/CD
• Cloudflare Deployment: Deploy to Cloudflare Pages with Edge runtime
• Docker Deployment: Self-host with Docker containers
• Environment Variables: Complete variable reference with Zod validation