Environment Variables Reference for the Next.js Supabase SaaS Kit

Complete reference for all environment variables in the Next.js Supabase SaaS Kit, including Supabase, Stripe, email, and feature flag configuration.

This page documents all environment variables used by the Next.js Supabase SaaS Kit. Variables are organized by category and include their purpose, required status, and default values.

Environment File Structure

FilePurposeGit Status
.envShared settings across all environmentsCommitted
.env.developmentDevelopment-specific overridesCommitted
.env.productionProduction-specific settingsCommitted
.env.localLocal secrets and overridesGit-ignored

Priority order: .env.local > .env.development/.env.production > .env

Required Variables

These variables must be set for the application to start:

# Supabase (required)
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=your-public-key
SUPABASE_SECRET_KEY=your-service-role-key
# App identity (required)
NEXT_PUBLIC_SITE_URL=https://yourapp.com
NEXT_PUBLIC_PRODUCT_NAME=Your Product
NEXT_PUBLIC_SITE_TITLE="Your Product - Tagline"
NEXT_PUBLIC_SITE_DESCRIPTION="Your product description"

Core Configuration

Site Identity

NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_PRODUCT_NAME=Makerkit
NEXT_PUBLIC_SITE_TITLE="Makerkit - Build SaaS Faster"
NEXT_PUBLIC_SITE_DESCRIPTION="Production-ready SaaS starter kit"
NEXT_PUBLIC_DEFAULT_LOCALE=en
VariableRequiredDescription
NEXT_PUBLIC_SITE_URLYesFull URL with protocol
NEXT_PUBLIC_PRODUCT_NAMEYesProduct name shown in UI
NEXT_PUBLIC_SITE_TITLEYesBrowser title and SEO
NEXT_PUBLIC_SITE_DESCRIPTIONYesMeta description
NEXT_PUBLIC_DEFAULT_LOCALENoDefault language (default: en)

Theme

NEXT_PUBLIC_DEFAULT_THEME_MODE=light
NEXT_PUBLIC_THEME_COLOR="#ffffff"
NEXT_PUBLIC_THEME_COLOR_DARK="#0a0a0a"
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
VariableOptionsDefaultDescription
NEXT_PUBLIC_DEFAULT_THEME_MODElight, dark, systemlightInitial theme
NEXT_PUBLIC_THEME_COLORHex colorRequiredLight theme color
NEXT_PUBLIC_THEME_COLOR_DARKHex colorRequiredDark theme color
NEXT_PUBLIC_ENABLE_THEME_TOGGLEtrue, falsetrueAllow theme switching

Supabase Configuration

NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=your-public-key
SUPABASE_SECRET_KEY=your-service-role-key
SUPABASE_DB_WEBHOOK_SECRET=your-webhook-secret
VariableRequiredDescription
NEXT_PUBLIC_SUPABASE_URLYesSupabase project URL
NEXT_PUBLIC_SUPABASE_PUBLIC_KEYYesPublic anon key
SUPABASE_SECRET_KEYYesService role key (keep secret)
SUPABASE_DB_WEBHOOK_SECRETNoWebhook verification secret

Authentication

NEXT_PUBLIC_AUTH_PASSWORD=true
NEXT_PUBLIC_AUTH_MAGIC_LINK=false
NEXT_PUBLIC_AUTH_OTP=false
NEXT_PUBLIC_AUTH_IDENTITY_LINKING=false
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
CAPTCHA_SECRET_TOKEN=
NEXT_PUBLIC_DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX=false
VariableDefaultDescription
NEXT_PUBLIC_AUTH_PASSWORDtrueEnable password auth
NEXT_PUBLIC_AUTH_MAGIC_LINKfalseEnable magic link auth
NEXT_PUBLIC_AUTH_OTPfalseEnable OTP auth
NEXT_PUBLIC_AUTH_IDENTITY_LINKINGfalseAllow identity linking
NEXT_PUBLIC_CAPTCHA_SITE_KEY-Cloudflare Turnstile site key
CAPTCHA_SECRET_TOKEN-Cloudflare Turnstile secret
NEXT_PUBLIC_DISPLAY_TERMS_AND_CONDITIONS_CHECKBOXfalseShow terms checkbox

Password Requirements

NEXT_PUBLIC_PASSWORD_REQUIRE_UPPERCASE=false
NEXT_PUBLIC_PASSWORD_REQUIRE_NUMBERS=false
NEXT_PUBLIC_PASSWORD_REQUIRE_SPECIAL_CHARS=false
NEXT_PUBLIC_USER_NAVIGATION_STYLE=sidebar
NEXT_PUBLIC_HOME_SIDEBAR_COLLAPSED=false
NEXT_PUBLIC_TEAM_NAVIGATION_STYLE=sidebar
NEXT_PUBLIC_TEAM_SIDEBAR_COLLAPSED=false
NEXT_PUBLIC_SIDEBAR_COLLAPSIBLE_STYLE=icon
NEXT_PUBLIC_ENABLE_SIDEBAR_TRIGGER=true
VariableOptionsDefaultDescription
NEXT_PUBLIC_USER_NAVIGATION_STYLEsidebar, headersidebarPersonal nav layout
NEXT_PUBLIC_HOME_SIDEBAR_COLLAPSEDtrue, falsefalseStart collapsed
NEXT_PUBLIC_TEAM_NAVIGATION_STYLEsidebar, headersidebarTeam nav layout
NEXT_PUBLIC_TEAM_SIDEBAR_COLLAPSEDtrue, falsefalseStart collapsed
NEXT_PUBLIC_SIDEBAR_COLLAPSIBLE_STYLEoffcanvas, icon, noneiconCollapse behavior
NEXT_PUBLIC_ENABLE_SIDEBAR_TRIGGERtrue, falsetrueShow collapse button

Feature Flags

NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=false
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=false
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=false
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=false
NEXT_PUBLIC_ENABLE_NOTIFICATIONS=true
NEXT_PUBLIC_REALTIME_NOTIFICATIONS=false
NEXT_PUBLIC_ENABLE_VERSION_UPDATER=false
NEXT_PUBLIC_LANGUAGE_PRIORITY=application
VariableDefaultDescription
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETIONfalseUsers can delete accounts
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLINGfalsePersonal subscription billing
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTStrueEnable team features
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATIONtrueUsers can create teams
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETIONfalseUsers can delete teams
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLINGfalseTeam subscription billing
NEXT_PUBLIC_ENABLE_NOTIFICATIONStrueIn-app notifications
NEXT_PUBLIC_REALTIME_NOTIFICATIONSfalseLive notification updates
NEXT_PUBLIC_ENABLE_VERSION_UPDATERfalseCheck for updates
NEXT_PUBLIC_LANGUAGE_PRIORITYapplicationuser or application

Billing Configuration

Provider Selection

NEXT_PUBLIC_BILLING_PROVIDER=stripe

Options: stripe or lemon-squeezy

Stripe

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
VariableRequiredDescription
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYYes (Stripe)Publishable key
STRIPE_SECRET_KEYYes (Stripe)Secret key
STRIPE_WEBHOOK_SECRETYes (Stripe)Webhook signing secret

Lemon Squeezy

LEMON_SQUEEZY_SECRET_KEY=your-secret-key
LEMON_SQUEEZY_STORE_ID=your-store-id
LEMON_SQUEEZY_SIGNING_SECRET=your-signing-secret
VariableRequiredDescription
LEMON_SQUEEZY_SECRET_KEYYes (LS)API secret key
LEMON_SQUEEZY_STORE_IDYes (LS)Store identifier
LEMON_SQUEEZY_SIGNING_SECRETYes (LS)Webhook signing secret

Email Configuration

Provider Selection

MAILER_PROVIDER=nodemailer

Options: nodemailer or resend

Common Settings

EMAIL_SENDER="Your App <noreply@yourapp.com>"
CONTACT_EMAIL=contact@yourapp.com

Resend

RESEND_API_KEY=re_...

Nodemailer (SMTP)

EMAIL_HOST=smtp.provider.com
EMAIL_PORT=587
EMAIL_USER=your-username
EMAIL_PASSWORD=your-password
EMAIL_TLS=true

CMS Configuration

Provider Selection

CMS_CLIENT=keystatic

Options: keystatic or wordpress

Keystatic

NEXT_PUBLIC_KEYSTATIC_STORAGE_KIND=local
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=./content
KEYSTATIC_PATH_PREFIX=apps/web

For GitHub storage:

NEXT_PUBLIC_KEYSTATIC_STORAGE_KIND=github
NEXT_PUBLIC_KEYSTATIC_STORAGE_REPO=owner/repo
KEYSTATIC_GITHUB_TOKEN=github_pat_...
VariableOptionsDescription
NEXT_PUBLIC_KEYSTATIC_STORAGE_KINDlocal, cloud, githubStorage backend
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATHPathContent directory
KEYSTATIC_PATH_PREFIXPathMonorepo prefix
NEXT_PUBLIC_KEYSTATIC_STORAGE_REPOowner/repoGitHub repository
KEYSTATIC_GITHUB_TOKENTokenGitHub access token

WordPress

WORDPRESS_API_URL=https://your-site.com/wp-json

Security Best Practices

  1. Never commit secrets: Use .env.local for sensitive values
  2. Use CI/CD variables: Store production secrets in your deployment platform
  3. Rotate keys regularly: Especially after team member changes
  4. Validate in production: The kit validates configuration at build time

Common Pitfalls

  1. HTTP in production: NEXT_PUBLIC_SITE_URL must use https:// in production builds.
  2. Same theme colors: NEXT_PUBLIC_THEME_COLOR and NEXT_PUBLIC_THEME_COLOR_DARK must be different.
  3. Missing Supabase keys: The app won't start without valid Supabase credentials.
  4. Forgetting to restart: After changing environment variables, you may need to restart the development server.
  5. Wrong file for secrets: Put secrets in .env.local (git-ignored), not .env (committed).