Environment Variables - kjanat/livedash-node GitHub Wiki

Environment Variables Setup

This document explains how to configure environment variables for the LiveDash Node.js application running on Cloudflare Workers with Next.js and Auth.js.

Overview

The application uses multiple environment files with a specific loading order:

  1. .env - Default fallback values (lowest priority)
  2. .env.development - Development-specific variables
  3. .env.production - Production-specific variables
  4. .env.local - Local overrides (highest priority, git-ignored)
  5. .dev.vars - Wrangler/Cloudflare Workers development variables (git-ignored)

Note: Later files override earlier ones. .env.local always has the highest priority for Next.js, while .dev.vars is used specifically by Wrangler for local Cloudflare Workers development.

File Descriptions

.env (Base Configuration)

Shared defaults and public variables that work across all environments.

Required Variables:

# NextAuth.js Base URL
NEXTAUTH_URL=http://localhost:3000

# JWT Secret (use random string in production)
NEXTAUTH_SECRET=your-secret-here

# Database Connection
DATABASE_URL="file:./dev.db"

.env.development (Development Settings)

Local development database connections, debug flags, and development-specific configurations.

Required Variables:

# Development environment flag
NODE_ENV=development

# Local development URL
NEXTAUTH_URL=http://localhost:3000

# Development JWT secret (can be fixed for consistency)
NEXTAUTH_SECRET=development-fixed-secret

# Local SQLite database
DATABASE_URL="file:./dev.db"

# Debug flags (optional)
AUTH_DEBUG=true

.env.production (Production Settings)

Production database URLs, API endpoints, and production-specific configurations.

Required Variables:

# Production environment flag
NODE_ENV=production

# Production URL
NEXTAUTH_URL=https://your-domain.com

# Production JWT secret (must be random and secure)
NEXTAUTH_SECRET=production-random-secret

# Cloudflare D1 database connection
DATABASE_URL="your-d1-connection-string"

.env.local (Personal Overrides)

Personal secrets, local overrides, and sensitive data. This file is git-ignored.

Required Variables:

# Personal auth secrets
AUTH_SECRET=your-random-secret

# OAuth Provider Credentials
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

# Personal database overrides (if needed)
DATABASE_URL="your-personal-db-connection"

# API Keys
CLOUDFLARE_API_TOKEN=your-cloudflare-token

.dev.vars (Wrangler Development Variables)

Used specifically by Wrangler for local Cloudflare Workers development. This file is git-ignored.

Required Variables:

# Auth secrets for Workers runtime
AUTH_SECRET=your-random-secret

# OAuth Provider Credentials (same as .env.local)
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

# Database connection for Workers
DATABASE_URL="file:./dev.db"

# Workers-specific variables
NODE_ENV=development
AUTH_URL=http://localhost:8787

Note: .dev.vars is used when running pnpm run preview or wrangler dev, while .env.local is used for pnpm run dev (Next.js dev server).

Auth.js v5 Configuration

With Auth.js v5, you can use automatic environment variable inference by following the AUTH_* naming convention:

OAuth Providers

# GitHub OAuth
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

# Google OAuth  
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

# Discord OAuth
AUTH_DISCORD_ID=your-discord-client-id
AUTH_DISCORD_SECRET=your-discord-client-secret

Core Auth Variables

# Required: Random secret for JWT signing
AUTH_SECRET=your-random-secret

# Optional: Custom auth URL
AUTH_URL=https://your-domain.com

# Optional: Trust proxy headers
AUTH_TRUST_HOST=true

Cloudflare-Specific Variables

Wrangler Configuration

These variables should also be configured in wrangler.jsonc:

# Cloudflare D1 Database
DATABASE_URL=your-d1-connection-string

# Worker Environment
NODE_ENV=production

# Compatibility settings
NODEJS_COMPAT=true

D1 Database Connection

# Development (local SQLite)
DATABASE_URL="file:./dev.db"

# Production (Cloudflare D1)
DATABASE_URL="cloudflare-d1://your-database-id"

Generating Secrets

AUTH_SECRET / NEXTAUTH_SECRET

Cross-platform command to generate a secure random secret:

# Using Node.js (works on all platforms)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Using OpenSSL (Linux/macOS/WSL)
openssl rand -hex 32

# Using PowerShell (Windows)
[System.Web.Security.Membership]::GeneratePassword(64, 0)

# Online alternative
# Visit: https://generate-secret.vercel.app/32

OAuth Client Secrets

These are provided by OAuth providers when you create applications:

Runtime Differences

Development (pnpm run dev)

  • Uses Next.js dev server (Node.js runtime)
  • Loads .env.development + .env.local
  • Uses local SQLite database
  • Hot reload enabled

Preview (pnpm run preview)

  • Uses Cloudflare Workers runtime (workerd)
  • Loads .dev.vars for environment variables
  • May have different environment variable handling
  • More accurate to production

Production Deployment

  • Cloudflare Workers runtime
  • Environment variables from Wrangler configuration
  • D1 database binding
  • Production OAuth callbacks

Example Complete Setup

.env

# Base configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=development-fallback-secret
DATABASE_URL="file:./dev.db"

.env.development

NODE_ENV=development
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=development-fixed-secret
DATABASE_URL="file:./dev.db"
AUTH_DEBUG=true

.env.production

NODE_ENV=production
NEXTAUTH_URL=https://livedash.your-domain.com
NEXTAUTH_SECRET=CHANGE-ME-TO-RANDOM-SECRET
DATABASE_URL="cloudflare-d1://your-d1-database-id"

.env.local (git-ignored)

# Generated with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
AUTH_SECRET=a8e6a602f61cc46530bf78ee9dfa9022528a5e1170b2b8687303f86934170319

# OAuth credentials from GitHub
AUTH_GITHUB_ID=your-actual-github-client-id
AUTH_GITHUB_SECRET=your-actual-github-client-secret

# Cloudflare API token (if needed for deployment)
CLOUDFLARE_API_TOKEN=your-actual-cloudflare-token

.dev.vars (git-ignored, for Wrangler)

# Same secrets as .env.local but for Wrangler/Workers development
AUTH_SECRET=a8e6a602f61cc46530bf78ee9dfa9022528a5e1170b2b8687303f86934170319
AUTH_GITHUB_ID=your-actual-github-client-id
AUTH_GITHUB_SECRET=your-actual-github-client-secret

# Workers-specific URL (different port from Next.js dev)
AUTH_URL=http://localhost:8787

# Database for Workers development
DATABASE_URL="file:./dev.db"

Cloudflare API token (if needed for deployment)

CLOUDFLARE_API_TOKEN=your-actual-cloudflare-token

Troubleshooting

Common Issues

  1. Environment variables not loading in preview mode

    • Run pnpm run cf-typegen to generate Cloudflare types
    • Check wrangler.jsonc configuration
    • Ensure .dev.vars file exists for Wrangler development

  2. Auth.js not finding variables

    • Ensure variables follow AUTH_* naming convention
    • Check .env.local exists for pnpm run dev
    • Check .dev.vars exists for pnpm run preview

  3. Database connection errors

    • Verify DATABASE_URL format for your environment
    • For D1: ensure database binding is configured in Wrangler

Verification Commands

# Check which environment variables are loaded
pnpm run dev --debug

# Generate Cloudflare environment types
pnpm run cf-typegen

# Test Wrangler configuration
wrangler dev --local

# Verify database connection
wrangler d1 execute your-db --command "SELECT 1"

Security Best Practices

  1. Never commit .env.local - It's git-ignored for a reason
  2. Use different secrets per environment - Development vs Production
  3. Rotate secrets regularly - Especially in production
  4. Use minimal permissions - For API tokens and OAuth apps
  5. Validate environment variables - In your application startup code

Related Documentation