Environment Configuration

The Next.js 15 StarShip Developer Kit is designed to be highly configurable through environment variables. This guide will walk you through all available environment variables and how to configure external services using our recommended environment file structure.

We recommend using the following environment file structure for proper separation between environments:

• .env.example - Template file with all environment variables (with empty values)
• .env - Common variables and documentation across all environments
• .env.development.local - Local development environment variables (ignored by Git)
• .env.production - Production environment variables

To get started quickly, copy the .env.example file to .env and fill in the values appropriate for your environment:

cp .env.example .env

This structure follows Next.js's environment loading prioritization:

1. .env.development.local - Highest priority, overrides everything else (local only)
2. .env.production - Loaded in production environments
3. .env - Lowest priority, provides defaults

Important: For more details on how Next.js handles environment variables and loading priority, see the official Next.js documentation (nextjs.org/docs/pages/guides/environment-variables).

Example .env file (shared defaults)

# Core Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

# Authentication Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32

# This file contains documentation and shared defaults
# Specific values should be in .env.development.local or .env.production

Example .env.development.local (for local development)

# Local Database Configuration
DATABASE_URL=postgresql://nextstarter:@localhost:5432/nextstarter?sslmode=disable

# Docker PostgreSQL Configuration
DB_USER=nextstarter
DB_PASSWORD=
DB_NAME=nextstarter
DB_PORT=5432

# Development Database (for sync)
DEVELOPMENT_DATABASE_URL=postgresql://postgres.supabase:password@aws-region.pooler.supabase.com:6543/postgres?sslmode=no-verify

# Supabase Development Project
NEXT_PUBLIC_SUPABASE_URL=your-dev-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-dev-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-dev-supabase-service-role-key

# OAuth for Development
GOOGLE_CLIENT_ID=your-dev-google-client-id
GOOGLE_CLIENT_SECRET=your-dev-google-client-secret

# Stripe Test Credentials
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-test-stripe-key
STRIPE_SECRET_KEY=your-test-stripe-secret
STRIPE_WEBHOOK_SECRET=your-test-webhook-secret

# OpenAI for Development
OPENAI_API_KEY=your-openai-key

Example .env.production (for production deployment)

# Production Database Configuration
DATABASE_URL=postgresql://postgres.supabase:password@aws-region.pooler.supabase.com:6543/postgres

# Supabase Production Project
NEXT_PUBLIC_SUPABASE_URL=your-prod-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-prod-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-prod-supabase-service-role-key

# OAuth for Production
GOOGLE_CLIENT_ID=your-prod-google-client-id
GOOGLE_CLIENT_SECRET=your-prod-google-client-secret

# Stripe Live Credentials
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-live-stripe-key
STRIPE_SECRET_KEY=your-live-stripe-secret
STRIPE_WEBHOOK_SECRET=your-live-webhook-secret

# OpenAI for Production
OPENAI_API_KEY=your-production-openai-key

The Next.js 15 StarShip Developer Kit includes a validation system for environment variables. This ensures that all required variables are set and have the correct format.

// Example of environment variable validation
import { z } from "zod";

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  NEXTAUTH_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(1),
  // Add more variables as needed
});

export function validateEnv() {
  try {
    envSchema.parse(process.env);
    return true;
  } catch (error) {
    console.error("Invalid environment variables:", error);
    return false;
  }
}

You can call this function at the start of your application to ensure all required environment variables are set correctly.

In Next.js, you can access environment variables in your code usingprocess.env:

// Server Component
export default function ServerComponent() {
  const databaseUrl = process.env.DATABASE_URL;
  // Use databaseUrl
}

// Client Component
"use client";

export default function ClientComponent() {
  const appUrl = process.env.NEXT_PUBLIC_APP_URL;
  // Use appUrl
}

Note that only variables prefixed with NEXT_PUBLIC_ are available in client components. All variables are available in server components.

1. Never commit environment files containing secrets to version control
2. Use descriptive comments to document the purpose of each variable
3. Keep database credentials, API keys, and other secrets in environment variables, never hardcode them
4. Use separate environment files for different environments (development, production)
5. Consider using a secret manager service for production environments
6. Use git-secrets or similar tools to prevent accidental commits of sensitive data