Environment Variables

This guide explains every environment variable in Bklit, what's required, and what's optional.

Quick Reference

Required (3 variables)

These are auto-generated by npx @bklit/create:

Optional (Everything Else)

All other variables enable optional features. Core analytics work without them.

Authentication

AUTH_SECRET (Required)

Purpose: Encrypts sessions and tokens

Auto-generated: Yes (32-byte random secret)

Manual generation:

openssl rand -base64 32

OAuth Providers (Optional)

Without OAuth: Email authentication (magic links) works automatically.

With OAuth: Users can sign in with GitHub/Google.

Databases

DATABASE_URL (Required)

Purpose: PostgreSQL connection for user data, projects, organizations

Auto-configured: Yes (with Docker)

Format:

postgresql://user:password@host:port/database

Docker default:

postgresql://bklit:generated-password@localhost:5432/bklit

CLICKHOUSE_HOST (Required)

Purpose: ClickHouse connection for analytics events

Auto-configured: Yes (with Docker)

Default:

http://localhost:8123

Credentials:

• Username: default
• Password: (empty for local Docker)

Billing (Optional)

Without Polar: All users have free tier access. Billing features hidden.

With Polar: Enable paid subscription plans.

Get credentials: Polar.sh Dashboard

Setup guide: Polar Setup

Email (Optional)

Without Resend: Emails log to console in development. Production requires Resend.

With Resend: Send transactional emails (welcome, password reset, invitations).

Development behavior:

# Email appears in terminal instead of being sent
📧 EMAIL (Development - Console Mode)
📬 To: [email protected]
📋 Subject: Verify your Bklit email
🔑 OTP: 123456

Get API key: Resend Dashboard

External Services (Optional)

Maps - Mapbox

Without Mapbox: Geographic data shows as list view.

With Mapbox: Interactive map visualization.

Get token: Mapbox (free tier available)

Background Jobs - Trigger.dev

Without Trigger.dev: Health checks and scheduled tasks disabled.

With Trigger.dev: Enable background jobs and monitoring.

Get credentials: Trigger.dev

Development vs Production

Development Environment

Set NODE_ENV=development to enable:

• OTP codes in terminal (no email needed)
• Email console logging
• Detailed error messages
• Hot reloading

Additional dev variables:

DEV_DATABASE_URL="..."        # Overrides DATABASE_URL in dev
DEV_CLICKHOUSE_HOST="..."     # Overrides CLICKHOUSE_HOST in dev

Production Environment

Set NODE_ENV=production for:

• Resend required for emails
• Enhanced security
• Optimized builds
• Error tracking

Health Monitoring (Optional)

Auto-generated: HEALTH_CHECK_SECRET is auto-generated by wizard.

App Configuration

Summary: What You Actually Need

For local development:

# These 3 are auto-generated by npx @bklit/create
AUTH_SECRET="..."
DATABASE_URL="postgresql://..."
CLICKHOUSE_HOST="http://localhost:8123"

# That's it! Everything else is optional.

For production:

# Required
AUTH_SECRET="..."
DATABASE_URL="postgresql://..."
CLICKHOUSE_HOST="https://..."
RESEND_API_KEY="..."  # Required in production for emails

# Recommended
AUTH_GITHUB_ID="..."  # For OAuth
POLAR_ACCESS_TOKEN="..."  # For billing
NEXT_PUBLIC_MAPBOX_TOKEN="..."  # For maps

# Optional
TRIGGER_SECRET_KEY="..."  # For background jobs

Quick Setup

Don't want to configure manually? Run:

npx @bklit/create

The wizard handles all of this automatically!