Skip to main content
Better Skills uses typed environment variables validated at runtime with Zod schemas.

​
Environment packages

Environment configuration is centralized in packages/env/ with three exports:
  • @better-skills/env/server - Server environment
  • @better-skills/env/web - Web app environment
  • @better-skills/env/cli - CLI environment
Environment variables are validated on startup. Missing or invalid variables will throw errors before the app runs.

​
Server environment

Required for apps/server/.

​
Location

apps/server/.env

​
Required variables

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/better_skills

# Better Auth
BETTER_AUTH_SECRET=your-32-character-secret-key-here
BETTER_AUTH_URL=http://localhost:3000

# CORS
CORS_ORIGIN=http://localhost:3001

# OAuth providers
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Environment
NODE_ENV=development

​
Variable descriptions

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@localhost:5432/db
BETTER_AUTH_SECRETSecret key for Better Auth (32+ chars)your-32-character-secret-key-here
BETTER_AUTH_URLBase URL for auth callbackshttp://localhost:3000
CORS_ORIGINAllowed CORS origin (web app URL)http://localhost:3001
GOOGLE_CLIENT_IDGoogle OAuth client IDFrom Google Cloud Console
GOOGLE_CLIENT_SECRETGoogle OAuth client secretFrom Google Cloud Console
GITHUB_CLIENT_IDGitHub OAuth client IDFrom GitHub OAuth Apps
GITHUB_CLIENT_SECRETGitHub OAuth client secretFrom GitHub OAuth Apps
NODE_ENVRuntime environmentdevelopment, production, or test
Never commit .env files to version control. Keep secrets secure.

​
Web environment

Required for apps/web/.

​
Location

apps/web/.env.local
Next.js reads from .env.local for local development. Use .env.production for production builds.

​
Required variables

NEXT_PUBLIC_SERVER_URL=http://localhost:3000

​
Variable descriptions

VariableDescriptionExample
NEXT_PUBLIC_SERVER_URLAPI server URL (exposed to browser)http://localhost:3000
Variables prefixed with NEXT_PUBLIC_ are embedded in the client bundle. Only use this prefix for non-sensitive URLs.

​
CLI environment

Required for apps/cli/.

​
Location

The CLI reads from:
  1. .env file in current directory
  2. Environment variables
  3. Default values

​
Variables

SERVER_URL=http://localhost:3000

​
Variable descriptions

VariableDescriptionDefault
SERVER_URLAPI server URLhttp://localhost:3000
SERVER_URL defaults to http://localhost:3000 if not specified.

​
Production configuration

​
Server production

apps/server/.env
DATABASE_URL=postgresql://user:pass@prod-host:5432/db?sslmode=require
BETTER_AUTH_SECRET=your-production-secret-min-32-chars
BETTER_AUTH_URL=https://api.better-skills.dev
CORS_ORIGIN=https://better-skills.dev
GOOGLE_CLIENT_ID=prod-google-client-id
GOOGLE_CLIENT_SECRET=prod-google-client-secret
GITHUB_CLIENT_ID=prod-github-client-id
GITHUB_CLIENT_SECRET=prod-github-client-secret
NODE_ENV=production

​
Web production

apps/web/.env.production
NEXT_PUBLIC_SERVER_URL=https://api.better-skills.dev

​
CLI production

For the installer script: 
SERVER_URL=https://api.better-skills.dev
Or override during installation: 
curl -fsSL https://better-skills.dev/install | bash -s -- --server-url https://api.better-skills.dev

​
Generating secrets

​
BETTER_AUTH_SECRET

Generate a secure 32+ character secret: 
openssl rand -base64 32
Or use Node.js: 
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

​
OAuth setup

​
Google OAuth

1

Create OAuth credentials

Go to Google Cloud Console.
2

Configure OAuth consent screen

Set up your app name and authorized domains.
3

Create OAuth 2.0 Client ID

Choose “Web application” and set:
  • Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
4

Copy credentials

Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to apps/server/.env.

​
GitHub OAuth

1

Register OAuth app

Go to GitHub Developer Settings.
2

Create new OAuth App

Set:
  • Homepage URL: http://localhost:3001
  • Authorization callback URL: http://localhost:3000/api/auth/callback/github
3

Copy credentials

Add GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to apps/server/.env.

​
Validation

All environment variables are validated at runtime. Invalid configuration will throw errors: 
❌ Invalid environment variables:
  DATABASE_URL: Required
  BETTER_AUTH_SECRET: String must contain at least 32 character(s)
  BETTER_AUTH_URL: Invalid url
Fix the errors and restart the app.

​
Turbo configuration

Turborepo is aware of environment variables listed in turbo.json:
turbo.json
{
  "globalEnv": [
    "DATABASE_URL",
    "BETTER_AUTH_SECRET",
    "BETTER_AUTH_URL",
    "CORS_ORIGIN",
    "GOOGLE_CLIENT_ID",
    "GOOGLE_CLIENT_SECRET",
    "GITHUB_CLIENT_ID",
    "GITHUB_CLIENT_SECRET"
  ]
}
This ensures Turbo invalidates caches when these variables change.

​
Troubleshooting

Ensure:
  1. .env files are in the correct locations
  2. Variable names match exactly (case-sensitive)
  3. No spaces around = signs
  4. No quotes needed for values
Verify:
  1. CORS_ORIGIN in server .env matches your web app URL
  2. NEXT_PUBLIC_SERVER_URL in web .env.local matches your server URL
  3. Both services are running
Check:
  1. Client IDs and secrets are correct
  2. Redirect URIs match exactly (including protocol)
  3. OAuth app is not in development mode (for Google)

​
Next steps

Development Setup

Return to development setup guide

Database Setup

Configure your database connection

Build docs developers (and LLMs) love

Get started for freeTalk to us