Skip to main content

​
Overview

Home Manager requires specific environment variables to function properly. This guide covers all required and optional environment variables you need to configure for your deployment.
Environment variables should be stored in a .env.local file for local development and configured in your hosting platform’s environment settings for production.

​
Required Environment Variables

​
Database Configuration

1

DATABASE_URL

PostgreSQL connection string for your database.
DATABASE_URL="postgresql://username:password@host:port/database?schema=public"
Format:
  • username: Your PostgreSQL username
  • password: Your PostgreSQL password
  • host: Database host (e.g., localhost or db.example.com)
  • port: Database port (default: 5432)
  • database: Database name
Examples:
DATABASE_URL="postgresql://postgres:password@localhost:5432/homemanager"

​
Authentication (Clerk)

Home Manager uses Clerk for authentication and user management.
1

CLERK_SECRET_KEY

Server-side secret key for Clerk API access.
CLERK_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxx"
Keep this secret! Never commit it to version control or expose it in client-side code.
Where to find it:
  1. Go to your Clerk Dashboard
  2. Select your application
  3. Navigate to API Keys
  4. Copy the Secret Key
2

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

Public key for client-side Clerk integration.
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_xxxxxxxxxxxxxxxxxxxxx"
The NEXT_PUBLIC_ prefix makes this variable accessible in the browser. This is safe because it’s a publishable key designed for client-side use.
Where to find it:
  • Same location as Secret Key in Clerk Dashboard
  • Copy the Publishable Key

​
Optional Environment Variables

​
Node Environment

NODE_ENV="production"
Specifies the environment mode. Affects:
  • Prisma connection pooling
  • Next.js optimizations
  • Logging verbosity
Values:
  • development - Local development (default)
  • production - Production deployment
  • test - Testing environment

​
Clerk Sign-In/Sign-Up URLs

Customize authentication redirect paths: 
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/dashboard"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/dashboard"
These are optional. Clerk will use sensible defaults if not specified.

​
Environment File Setup

​
Local Development

Create a .env.local file in the project root:
1

Create Environment File

touch .env.local
2

Add Required Variables

.env.local
# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/homemanager"

# Clerk Authentication
CLERK_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxx"
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_xxxxxxxxxxxxxxxxxxxxx"

# Optional: Custom Auth URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/dashboard"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/dashboard"
3

Verify Configuration

npm run dev
The application should start without errors. Check the console for any missing environment variable warnings.
Security Best Practices:
  • Never commit .env.local or .env files to version control
  • Add .env*.local to your .gitignore file
  • Use different Clerk keys for development and production
  • Rotate secrets regularly
  • Use strong, unique passwords for database connections

​
Production Environment

​
Platform-Specific Configuration

# Configure via Vercel Dashboard or CLI
vercel env add DATABASE_URL
vercel env add CLERK_SECRET_KEY
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

​
Verification

After setting environment variables, verify your configuration:
1

Check Database Connection

npx prisma db pull
Should connect successfully without errors.
2

Test Build

npm run build
The build should complete successfully with Prisma client generation.
3

Verify Clerk Integration

Start the application and navigate to /sign-in. The Clerk sign-in component should load properly.

​
Troubleshooting

​
Database Connection Issues

Error: Can't reach database serverSolutions:
  • Verify DATABASE_URL format is correct
  • Check database server is running
  • Ensure network access (firewall/security groups)
  • Verify credentials are correct
  • For cloud databases, check IP allowlist

​
Clerk Authentication Issues

Error: Clerk: Missing publishable keySolutions:
  • Ensure NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is set
  • For Next.js, restart dev server after adding environment variables
  • Check key starts with pk_test_ or pk_live_
  • Verify key is copied completely without extra spaces

​
Build Failures

Error: Prisma Client could not be generatedSolutions:
  • Ensure DATABASE_URL is set during build
  • Run npx prisma generate manually
  • Check package.json has postinstall script
  • Verify network connectivity to database during build

​
Next Steps

Database Setup

Configure PostgreSQL and run Prisma migrations

Deployment Guide

Deploy to Vercel, Docker, or custom servers

Build docs developers (and LLMs) love

Get started for freeTalk to us