Skip to main content
ZapDev requires several environment variables to be configured for proper operation. This page documents all variables, their purpose, and where to obtain them.

​
Configuration File

Create a .env file in your project root with the following variables: 
cp env.example .env
Then fill in the values as described below.

​
Required Variables

These variables are essential for ZapDev to function.

​
Application URL

​
NEXT_PUBLIC_APP_URL
string
required
The base URL of your application. Use http://localhost:3000 for development, or your production domain for deployment.Example: https://zapdev.example.com

​
Clerk Authentication

​
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
string
required
Public key for Clerk authentication. Get this from Clerk Dashboard → Your App → API Keys.Format: pk_test_... or pk_live_...
​
CLERK_SECRET_KEY
string
required
Secret key for Clerk authentication. Get this from Clerk Dashboard → Your App → API Keys.Format: sk_test_... or sk_live_...Security: Never commit this to version control.
​
CLERK_JWT_ISSUER_DOMAIN
string
required
JWT issuer domain for Convex integration. Get this from Clerk Dashboard → JWT Templates → Convex template.Example: https://your-app.clerk.accounts.dev
​
CLERK_JWT_TEMPLATE_NAME
string
required
Name of the JWT template for Convex. Must be set to "convex".Default: convex

​
Convex Database

​
NEXT_PUBLIC_CONVEX_URL
string
required
Your Convex deployment URL. Get this from Convex Dashboard after creating a project.Format: https://your-project.convex.cloud
​
NEXT_PUBLIC_CONVEX_SITE_URL
string
required
The site URL for Convex authentication. Should match your application URL.Example: https://zapdev.example.com

​
Stack Auth (Authentication)

​
NEXT_PUBLIC_STACK_PROJECT_ID
string
required
Your Stack Auth project ID. Get this from Stack Auth Dashboard.Format: UUID string
​
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY
string
required
Public client key for Stack Auth. Get this from Stack Auth Dashboard → API Keys.Format: Starts with pk_
​
STACK_SECRET_SERVER_KEY
string
required
Secret server key for Stack Auth. Get this from Stack Auth Dashboard → API Keys.Security: Never commit this to version control.

​
OpenRouter API (AI Models)

​
OPENROUTER_API_KEY
string
required
API key for OpenRouter AI gateway. Get this from OpenRouter Dashboard.Format: Starts with sk-or-
​
OPENROUTER_BASE_URL
string
required
Base URL for OpenRouter API.Default: https://openrouter.ai/api/v1

​
Billing & Subscriptions

​
Polar.sh

​
POLAR_ACCESS_TOKEN
string
required
Access token for Polar.sh API. Get this from Polar.sh Dashboard → Settings → API Keys.Security: Never commit this to version control.
​
POLAR_WEBHOOK_SECRET
string
required
Webhook secret for verifying Polar.sh webhooks. Get this from Polar.sh Dashboard → Webhooks.Security: Never commit this to version control.
​
NEXT_PUBLIC_POLAR_ORGANIZATION_ID
string
required
Your Polar.sh organization ID. Get this from Polar.sh Dashboard → Organization Settings.Format: UUID string
​
NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID
string
required
Product ID for the Pro subscription tier. Get this from Polar.sh Dashboard → Products → Pro.Format: UUID string
​
NEXT_PUBLIC_POLAR_PRO_PRICE_ID
string
required
Price ID for the Pro monthly subscription. Get this from Polar.sh Dashboard → Products → Pro → Pricing.Format: UUID string
​
NEXT_PUBLIC_POLAR_PRO_YEARLY_PRICE_ID
string
required
Price ID for the Pro yearly subscription. Get this from Polar.sh Dashboard → Products → Pro → Pricing.Format: UUID string
​
NEXT_PUBLIC_POLAR_UNLIMITED_PRODUCT_ID
string
required
Product ID for the Unlimited subscription tier. Get this from Polar.sh Dashboard → Products → Unlimited.Format: UUID string
​
NEXT_PUBLIC_POLAR_UNLIMITED_PRICE_ID
string
required
Price ID for the Unlimited monthly subscription. Get this from Polar.sh Dashboard → Products → Unlimited → Pricing.Format: UUID string
​
NEXT_PUBLIC_POLAR_SERVER
string
required
Polar.sh server environment. Use "sandbox" for testing, "production" for live.Default: productionOptions: sandbox | production

​
Optional Services

​
Cerebras API (Fast Inference)

​
CEREBRAS_API_KEY
string
API key for Cerebras Z.AI GLM 4.7 model (ultra-fast inference). Get this from Cerebras Cloud.Optional: Falls back to OpenRouter if not provided.

​
Vercel AI Gateway (Fallback)

​
VERCEL_AI_GATEWAY_API_KEY
string
API key for Vercel AI Gateway (used as fallback for Cerebras rate limits). Get this from Vercel Dashboard → AI Gateway.Optional: Only needed if using Cerebras with fallback.
​
BRAVE_SEARCH_API_KEY
string
API key for Brave Search API (enables web search in subagents). Get this from Brave Search API Dashboard.Optional: Web search features require this.

​
Firecrawl (Web Scraping)

​
FIRECRAWL_API_KEY
string
API key for Firecrawl web scraping service. Get this from Firecrawl Dashboard.Optional: Web scraping features require this.

​
OAuth Providers

​
GOOGLE_CLIENT_ID
string
OAuth client ID for Google authentication. Get this from Google Cloud Console.Optional: Only needed for Google OAuth.
​
GOOGLE_CLIENT_SECRET
string
OAuth client secret for Google authentication.Security: Never commit this to version control.
​
GITHUB_CLIENT_ID
string
OAuth client ID for GitHub authentication. Get this from GitHub Developer Settings.Optional: Only needed for GitHub OAuth.
​
GITHUB_CLIENT_SECRET
string
OAuth client secret for GitHub authentication.Security: Never commit this to version control.
​
FIGMA_CLIENT_ID
string
OAuth client ID for Figma integration. Get this from Figma Developer Settings.Optional: Only needed for Figma imports.
​
FIGMA_CLIENT_SECRET
string
OAuth client secret for Figma integration.Security: Never commit this to version control.

​
Monitoring & Error Tracking

​
NEXT_PUBLIC_SENTRY_DSN
string
Public Sentry DSN for client-side error tracking. Get this from Sentry Dashboard → Settings → Projects → Client Keys (DSN).Optional: Required for production error monitoring.
​
SENTRY_DSN
string
Sentry DSN for server-side error tracking.Optional: Can be same as NEXT_PUBLIC_SENTRY_DSN.

​
File Upload Service

​
UPLOADTHING_TOKEN
string
API token for UploadThing file upload service. Get this from UploadThing Dashboard.Optional: Required for file upload features.

​
Environment-Specific Configuration

​
Development (.env.local)

For local development, create a .env.local file: 
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_CONVEX_URL="https://your-dev-project.convex.cloud"
NEXT_PUBLIC_POLAR_SERVER="sandbox"
# ... other variables

​
Production (Vercel)

In Vercel Dashboard → Your Project → Settings → Environment Variables, add:
  1. All required variables from this page
  2. Set NEXT_PUBLIC_APP_URL to your production domain
  3. Set NEXT_PUBLIC_POLAR_SERVER to "production"
  4. Use production API keys (not test/sandbox keys)

​
Staging

For staging environments: 
NEXT_PUBLIC_APP_URL="https://staging.zapdev.example.com"
NEXT_PUBLIC_POLAR_SERVER="sandbox"
# ... use test/sandbox keys

​
Security Best Practices

Never commit secrets to version control! Always use .env.local for local development and environment variable management in your deployment platform.

​
Checklist

  • Add .env and .env.local to .gitignore
  • Use different API keys for development and production
  • Rotate secrets regularly (every 90 days)
  • Use secret management tools (Vercel Environment Variables, AWS Secrets Manager, etc.)
  • Never expose secret keys in client-side code
  • Audit environment variables before deployment

​
Variables by Visibility

Public (NEXT_PUBLIC_*): Can be exposed to the browser
  • NEXT_PUBLIC_APP_URL
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • NEXT_PUBLIC_CONVEX_URL
  • NEXT_PUBLIC_STACK_PROJECT_ID
  • NEXT_PUBLIC_POLAR_*
  • NEXT_PUBLIC_SENTRY_DSN
Private (Server-only): Must never be exposed
  • CLERK_SECRET_KEY
  • STACK_SECRET_SERVER_KEY
  • OPENROUTER_API_KEY
  • POLAR_ACCESS_TOKEN
  • POLAR_WEBHOOK_SECRET
  • *_CLIENT_SECRET variables

​
Validation

ZapDev validates environment variables at build time. If required variables are missing, the build will fail with an error message. To test your configuration locally: 
# Start development server
bun run dev

# Check for validation errors in terminal

​
Troubleshooting

​
Build Fails with “Missing Environment Variable”

Solution: Ensure all required variables are set in your .env or deployment platform.

​
”Invalid API Key” Errors

Solution: Verify the API key is correct and hasn’t expired. Check you’re using the right environment (test vs. production).

​
OAuth Redirect Errors

Solution: Ensure NEXT_PUBLIC_APP_URL matches the redirect URL configured in OAuth provider settings.

​
Webhook Verification Failures

Solution: Verify webhook secrets match exactly between your .env and the service dashboard (Polar.sh).

​
Next Steps

Database Setup

Configure and deploy your Convex database schema

Build docs developers (and LLMs) love

Get started for freeTalk to us