Environment Variables Reference

Single source of truth for all TinyKit Pro environment configuration.

Quick Start

# 1. Copy example file
cp .env.local.example .env.local

# 2. Run interactive setup (recommended)
bun setup

# 3. Start development
bun dev

The setup wizard configures most variables automatically. This guide covers manual configuration and production setup.

Quick Reference Tables

Frontend Variables (`.env.local`)

Variable	Required	Default	Description
`PORT`	No	`3000`	Development server port
`NEXT_PUBLIC_SITE_URL`	Yes	—	Full site URL (e.g., `http://localhost:3000`)
`SITE_DOMAIN`	Yes	—	Domain without protocol (e.g., `localhost`)
`CONVEX_DEPLOYMENT`	Yes	—	Convex deployment ID (e.g., `dev:project-name`)
`NEXT_PUBLIC_CONVEX_URL`	Yes	—	Convex API endpoint
`NEXT_PUBLIC_CONVEX_SITE_URL`	Yes	—	Convex site endpoint
`NEXT_PUBLIC_POSTHOG_KEY`	No	—	PostHog analytics key
`NEXT_PUBLIC_POSTHOG_HOST`	No	—	PostHog host URL
`NEXT_PUBLIC_LOG_LEVEL`	No	Auto	Frontend log level (DEBUG/INFO/WARN/ERROR)

Backend Variables (Convex Environment)

Variable	Required	Default	Description
`BETTER_AUTH_SECRET`	Yes	—	JWT signing secret (auto-generated by setup)
`SITE_URL`	Yes	—	Base URL for auth callbacks
`STRIPE_SECRET_KEY`	Yes*	—	Stripe API key (test or live)
`STRIPE_WEBHOOKS_SECRET`	Yes*	—	Stripe webhook signing secret
`RESEND_API_KEY`	No	—	Email sending (graceful degradation if missing)
`RESEND_TEST_MODE`	No	—	Enable email sandbox mode
`CONVEX_ENV`	No	Auto	Environment type (development/preview/production)
`LOG_LEVEL`	No	Auto	Backend log level (DEBUG/INFO/WARN/ERROR)
`GITHUB_CLIENT_ID`	No	—	GitHub OAuth app ID
`GITHUB_CLIENT_SECRET`	No	—	GitHub OAuth secret
`GOOGLE_CLIENT_ID`	No	—	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	—	Google OAuth secret
`AUTH_APPLE_ID`	No	—	Apple Sign In service ID
`AUTH_APPLE_SECRET`	No	—	Apple Sign In private key

*Required for billing features

Frontend Variables

Site Configuration

# Required: Full URL including protocol
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Required: Domain only, no protocol
SITE_DOMAIN=localhost

These are used for:

Metadata generation (og:url, canonical links)
Auth callback URLs
API redirects

Convex Configuration

# Your deployment identifier
CONVEX_DEPLOYMENT=dev:your-project-name

# Convex API endpoint
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

# Convex HTTP endpoint (for webhooks)
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site

Get these values from:

bun setup (automatic)
Convex Dashboard → Project Settings

Analytics (Optional)

# PostHog product analytics
NEXT_PUBLIC_POSTHOG_KEY=phc_your_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Enable via PostHog for user analytics and feature flags.

Logging (Optional)

# Override auto-detection
NEXT_PUBLIC_LOG_LEVEL=DEBUG  # DEBUG | INFO | WARN | ERROR

Auto-detection priority:

NEXT_PUBLIC_LOG_LEVEL (manual override)
NEXT_PUBLIC_VERCEL_ENV (Vercel deployments)
NODE_ENV (standard Next.js)
Default: INFO

Backend Variables

All backend variables are set via Convex environment, not .env.local.

Setting Variables

# Development
npx convex env set VARIABLE_NAME "value"

# Production
npx convex env set VARIABLE_NAME "value" --prod

# List current variables
npx convex env list

Authentication (Required)

# Generate a secure secret
openssl rand -base64 32

# Set in Convex
npx convex env set BETTER_AUTH_SECRET "your-generated-secret"
npx convex env set SITE_URL "http://localhost:3000"

BETTER_AUTH_SECRET: Used for JWT signing. Generate a unique value for each environment.

SITE_URL: Base URL for auth callbacks and email links.

Stripe (Required for Billing)

npx convex env set STRIPE_SECRET_KEY "sk_test_..."
npx convex env set STRIPE_WEBHOOKS_SECRET "whsec_..."

Get these from:

Stripe Dashboard → Developers → API Keys
Webhooks → Your endpoint → Signing secret

Note: No publishable key needed—TinyKit Pro uses Convex backend actions for all Stripe operations.

See Stripe Setup Guide for complete configuration.

Email (Optional)

npx convex env set RESEND_API_KEY "re_..."
npx convex env set RESEND_TEST_MODE "true"  # Development only

Graceful degradation: If RESEND_API_KEY is not set, email features are disabled but the application continues to work.

Important: Email configuration (support email, domain, site name) is managed through Admin Panel → Site Settings → Email Configuration, not environment variables.

See Email Setup Guide for complete configuration.

OAuth Providers (Optional)

Providers are automatically enabled when credentials are set.

GitHub:

npx convex env set GITHUB_CLIENT_ID "your_client_id"
npx convex env set GITHUB_CLIENT_SECRET "your_client_secret"

Google:

npx convex env set GOOGLE_CLIENT_ID "your_client_id"
npx convex env set GOOGLE_CLIENT_SECRET "your_client_secret"

Apple:

npx convex env set AUTH_APPLE_ID "your_service_id"
npx convex env set AUTH_APPLE_SECRET "your_private_key"

Callback URLs for OAuth apps:

GitHub: https://[your-convex-site].convex.site/api/auth/callback/github
Google: https://[your-convex-site].convex.site/api/auth/callback/google
Apple: https://[your-convex-site].convex.site/api/auth/callback/apple

See Authentication Setup Guide for detailed OAuth configuration.

Logging (Optional)

npx convex env set CONVEX_ENV "development"  # development | preview | staging | production
npx convex env set LOG_LEVEL "DEBUG"         # DEBUG | INFO | WARN | ERROR

Default log levels by environment:

development → DEBUG (all logs)
preview/staging → INFO (info and above)
production → ERROR (errors only)

Environment-Specific Setup

Development

# Frontend (.env.local)
NEXT_PUBLIC_SITE_URL=http://localhost:3000
SITE_DOMAIN=localhost

# Backend (Convex)
npx convex env set SITE_URL "http://localhost:3000"
npx convex env set CONVEX_ENV "development"
npx convex env set RESEND_TEST_MODE "true"  # Use email sandbox

Preview/Staging (Vercel)

# Vercel sets automatically:
# VERCEL_ENV=preview
# NEXT_PUBLIC_VERCEL_ENV=preview

# Backend (Convex - switch to preview deployment first)
npx convex env set SITE_URL "https://your-preview-url.vercel.app"
npx convex env set CONVEX_ENV "preview"

Production

# Frontend (Vercel Environment Variables)
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
SITE_DOMAIN=yourdomain.com
CONVEX_DEPLOYMENT=prod:your-project
NEXT_PUBLIC_LOG_LEVEL=WARN

# Backend (Convex - production deployment)
npx convex env set SITE_URL "https://yourdomain.com" --prod
npx convex env set BETTER_AUTH_SECRET "new-production-secret" --prod
npx convex env set STRIPE_SECRET_KEY "sk_live_..." --prod
npx convex env set STRIPE_WEBHOOKS_SECRET "whsec_live_..." --prod
npx convex env set CONVEX_ENV "production" --prod

Security note: Generate a new BETTER_AUTH_SECRET for production—never reuse development secrets.

See Production Checklist for complete deployment guide.

Troubleshooting

Common Issues

"Missing environment variables" error

# Check what's set
npx convex env list

# Verify required variables
npx convex env list | grep -E "BETTER_AUTH_SECRET|SITE_URL"

Convex not connecting

# Re-authenticate
npx convex auth

# Check deployment status
npx convex status

OAuth login failing

Verify callback URLs match exactly (including trailing slashes)
Check OAuth app is not in sandbox/development mode
Verify client ID and secret are for the correct environment

Emails not sending

# Check if RESEND_API_KEY is set
npx convex env list | grep RESEND

# If not set, email features are disabled (this is expected)

Logs not appearing

# Check log level
npx convex env list | grep LOG_LEVEL

# Set to DEBUG for all logs
npx convex env set LOG_LEVEL "DEBUG"

Debug Commands

# View live Convex logs
npx convex logs --tail

# Filter by category
npx convex logs --tail | grep "auth\|stripe\|email"

# Check all environment variables
npx convex env list

Stripe Setup — Webhook configuration, product sync, test cards
Email Setup — Resend configuration, email templates, domain verification
Authentication Setup — OAuth provider configuration, password requirements
Production Checklist — Complete deployment checklist
Setup Wizard — Interactive setup options

← Back to Guides | Getting Started →

Environment Variables Reference

On this page