# Environment Core Examples

> Essential environment configuration patterns. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for decision frameworks.

**Additional Examples:**

- [naming-and-templates.md](naming-and-templates.md) - Framework prefixes, .env.example
- [security-and-secrets.md](security-and-secrets.md) - Secret management
- [feature-flags-and-config.md](feature-flags-and-config.md) - Feature flags, centralized config

---

## Per-App Environment Files

### Good Example - Per-app environment files

```typescript
// apps/client-next/.env
NEXT_PUBLIC_API_URL=http://localhost:3000/api/v1

// apps/server/.env.example
# Base configuration
NODE_ENV=development
PORT=1337
```

**Why good:** Per-app configuration prevents conflicts in monorepo, clear defaults reduce onboarding friction, .env.example serves as documentation template

### Bad Example - Root-level .env

```typescript
// .env (root level - AVOID)
NEXT_PUBLIC_API_URL=http://localhost:3000/api/v1
DATABASE_URL=postgresql://localhost:5432/mydb
PORT=1337
```

**Why bad:** Root-level .env causes shared variables across apps with different needs, larger blast radius when misconfigured, unclear ownership

---

## Type-Safe Environment Variables with Zod

### Good Example - Zod validation at startup

```typescript
// lib/env.ts
import { z } from "zod";

const DEFAULT_API_TIMEOUT_MS = 30000;

const envSchema = z.object({
  // Public variables (VITE_ prefix)
  VITE_API_URL: z.string().url(),
  VITE_API_TIMEOUT: z.coerce.number().default(DEFAULT_API_TIMEOUT_MS),
  // Use z.stringbool() for boolean env vars (Zod 4+)
  // Correctly handles "true"/"false"/"1"/"0"/"yes"/"no"
  VITE_ENABLE_ANALYTICS: z.stringbool().default(false),
  VITE_ENVIRONMENT: z.enum(["development", "staging", "production"]),

  // Build-time variables
  MODE: z.enum(["development", "production"]),
  DEV: z.boolean(),
  PROD: z.boolean(),
});

// Validate and export
function validateEnv() {
  try {
    return envSchema.parse(import.meta.env);
  } catch (error) {
    if (error instanceof z.ZodError) {
      console.error("Invalid environment variables:");
      error.issues.forEach((err) => {
        console.error(`  - ${err.path.join(".")}: ${err.message}`);
      });
      throw new Error("Invalid environment configuration");
    }
    throw error;
  }
}

export const env = validateEnv();

// Type-safe usage
console.log(env.VITE_API_URL); // string
console.log(env.VITE_API_TIMEOUT); // number
console.log(env.VITE_ENABLE_ANALYTICS); // boolean
```

**Why good:** Type safety prevents runtime errors from typos or wrong types, runtime validation fails fast at startup with clear error messages, default values reduce required configuration, IDE autocomplete improves DX

### Bad Example - No validation

```typescript
// lib/config.ts
const API_URL = import.meta.env.VITE_API_URL; // Could be undefined!
const TIMEOUT = Number(import.meta.env.VITE_API_TIMEOUT); // Could be NaN!
```

**Why bad:** No validation means runtime failures with unclear error messages, type coercion fails silently (NaN), missing variables only discovered during usage not startup

---

### Bad Example - Using z.coerce.boolean() for env vars

```typescript
// lib/env.ts - WRONG!
const envSchema = z.object({
  // DON'T use z.coerce.boolean() for env vars!
  VITE_ENABLE_ANALYTICS: z.coerce.boolean().default(false),
});

// Problem: z.coerce.boolean() uses JavaScript's Boolean()
// Boolean("false") === true (non-empty string is truthy!)
// Boolean("0") === true
// This breaks env var semantics where "false" should mean false
```

**Why bad:** `z.coerce.boolean()` converts ANY non-empty string to `true` including "false", "0", "no" - use `z.stringbool()` (Zod 4+) which correctly parses "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off"/"enabled"/"disabled"

# Feature Flags and Configuration

> Environment-based feature flags and centralized configuration patterns. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for essential patterns.

**Related Examples:**

- [core.md](core.md) - Per-app .env, Zod validation
- [naming-and-templates.md](naming-and-templates.md) - Framework prefixes, .env.example
- [security-and-secrets.md](security-and-secrets.md) - Secret management

---

## Feature Flags with Environment Variables

### Good Example - Type-safe feature flags

```typescript
// lib/feature-flags.ts
export const FEATURES = {
  // Core features
  NEW_DASHBOARD: import.meta.env.VITE_FEATURE_NEW_DASHBOARD === "true",
  BETA_EDITOR: import.meta.env.VITE_FEATURE_BETA_EDITOR === "true",

  // Analytics & Monitoring
  ANALYTICS: import.meta.env.VITE_ENABLE_ANALYTICS === "true",
  ERROR_TRACKING: import.meta.env.VITE_ENABLE_ERROR_TRACKING === "true",

  // Environment-specific
  DEBUG_MODE: import.meta.env.DEV,
  MOCK_API: import.meta.env.VITE_MOCK_API === "true",
} as const;

// Type-safe feature check
export function isFeatureEnabled(feature: keyof typeof FEATURES): boolean {
  return FEATURES[feature];
}

export const { NEW_DASHBOARD, BETA_EDITOR, ANALYTICS } = FEATURES;
```

```typescript
// Usage in components
import { NEW_DASHBOARD } from "./feature-flags";
import { lazy } from "react";

// Code splitting based on feature flag
const Dashboard = NEW_DASHBOARD
  ? lazy(() => import("./features/dashboard-v2"))
  : lazy(() => import("./features/dashboard-v1"));
```

**Why good:** Type-safe flags prevent typos, centralized configuration makes flags discoverable, code splitting reduces bundle size for disabled features, no external dependencies reduces complexity

### Bad Example - Inline feature checks

```typescript
// components/dashboard.tsx
function Dashboard() {
  // Reading env var directly everywhere
  if (process.env.NEXT_PUBLIC_FEATURE_NEW_DASHBOARD === "true") {
    return <NewDashboard />;
  }
  return <LegacyDashboard />;
}
```

**Why bad:** Inline checks scatter feature flag logic across codebase, no type safety means typos fail silently, hard to discover all feature flags, duplicated string comparisons

---

## Environment-Specific Configuration

### Good Example - Centralized config with env overrides

```typescript
// lib/config.ts
import { env } from "./env";

const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
const DEFAULT_CACHE_MAX_SIZE = 100;
const DEFAULT_RETRY_ATTEMPTS = 3;

interface AppConfig {
  api: {
    baseUrl: string;
    timeout: number;
    retryAttempts: number;
  };
  features: {
    analytics: boolean;
    errorTracking: boolean;
    debugMode: boolean;
  };
  cache: {
    ttl: number;
    maxSize: number;
  };
}

function getConfig(): AppConfig {
  const baseConfig: AppConfig = {
    api: {
      baseUrl: env.VITE_API_URL,
      timeout: env.VITE_API_TIMEOUT,
      retryAttempts: DEFAULT_RETRY_ATTEMPTS,
    },
    features: {
      analytics: env.VITE_ENABLE_ANALYTICS,
      errorTracking: false,
      debugMode: env.DEV,
    },
    cache: {
      ttl: DEFAULT_CACHE_TTL_MS,
      maxSize: DEFAULT_CACHE_MAX_SIZE,
    },
  };

  // Environment-specific overrides
  const envConfigs: Record<string, Partial<AppConfig>> = {
    development: {
      cache: { ttl: 0, maxSize: 0 }, // No caching in dev
      features: { debugMode: true },
    },
    production: {
      cache: { ttl: 15 * 60 * 1000, maxSize: 500 },
      features: { errorTracking: true, debugMode: false },
    },
  };

  const envOverrides = envConfigs[env.VITE_ENVIRONMENT] || {};

  return {
    ...baseConfig,
    ...envOverrides,
    api: { ...baseConfig.api, ...envOverrides.api },
    features: { ...baseConfig.features, ...envOverrides.features },
    cache: { ...baseConfig.cache, ...envOverrides.cache },
  };
}

export const config = getConfig();
```

```typescript
// Usage
import { config } from "./config";

fetch(config.api.baseUrl, {
  signal: AbortSignal.timeout(config.api.timeout),
});

if (config.features.analytics) {
  trackEvent("page_view");
}
```

**Why good:** Centralized configuration provides single source of truth for app behavior, environment-specific overrides enable different settings per environment (dev vs prod), type-safe access prevents runtime errors from typos, easy to test with mock config injection

### Bad Example - Scattered configuration

```typescript
// Multiple files reading env vars directly
// api-client.ts
const timeout = Number(process.env.VITE_API_TIMEOUT);

// analytics.ts
const enabled = process.env.VITE_ENABLE_ANALYTICS === "true";

// cache.ts
const ttl = process.env.VITE_CACHE_TTL || "300000";
```

**Why bad:** Scattered configuration makes it hard to understand app behavior, no centralized type safety, duplicated env var parsing logic, difficult to test or mock

# Naming Conventions and Templates

> Framework-specific naming and .env.example documentation patterns. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for essential patterns.

**Related Examples:**

- [core.md](core.md) - Per-app .env, Zod validation
- [security-and-secrets.md](security-and-secrets.md) - Secret management
- [feature-flags-and-config.md](feature-flags-and-config.md) - Feature flags, centralized config

---

## Framework-Specific Naming Conventions

### Good Example - Framework-specific prefixes

```bash
# apps/client-next/.env

# Client-side variables (embedded in bundle)
NEXT_PUBLIC_API_URL=http://localhost:3000/api/v1
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789-1
NEXT_PUBLIC_ENVIRONMENT=development
NEXT_PUBLIC_FEATURE_NEW_DASHBOARD=true

# Server-side variables (not exposed to client)
DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET_KEY=super-secret-key-12345
STRIPE_SECRET_KEY=sk_test_...
JWT_SECRET=jwt-secret-key
```

**Why good:** `NEXT_PUBLIC_*` prefix makes client-side variables explicit preventing accidental secret exposure, server-side variables never embedded in bundle, clear separation improves security

### Bad Example - Missing prefixes and poor naming

```bash
# .env

# No framework prefix - unclear if client-side
API_URL=http://localhost:3000/api/v1

# Inconsistent casing
apiUrl=https://api.example.com
Database_Url=postgresql://localhost/db

# Unclear names
URL=https://api.example.com
KEY=12345
FLAG=true
```

**Why bad:** Missing framework prefix makes it unclear if variable is client-side or server-side, inconsistent casing reduces readability, unclear names make purpose ambiguous

---

## .env.example Templates

### Good Example - Comprehensive .env.example

```bash
# .env.example

# ================================================================
# IMPORTANT: Copy this file to .env and fill in the values
# ================================================================
# cp .env.example .env

# ====================================
# API Configuration (Required)
# ====================================

# Base URL for API requests
# Development: http://localhost:3000/api/v1
# Production: https://api.example.com/api/v1
NEXT_PUBLIC_API_URL=http://localhost:3000/api/v1

# API request timeout in milliseconds (optional, default: 30000)
# Range: 1000-60000
NEXT_PUBLIC_API_TIMEOUT_MS=30000

# Number of retry attempts (optional, default: 3)
NEXT_PUBLIC_API_RETRY_ATTEMPTS=3

# ====================================
# Database Configuration (Server-side)
# ====================================

# PostgreSQL connection string (required for server)
# Format: postgresql://username:password@host:port/database
DATABASE_URL=

# Database pool size (optional, default: 10)
DATABASE_POOL_SIZE=10

# ====================================
# Feature Flags (Optional)
# ====================================

# Enable new dashboard (default: false)
NEXT_PUBLIC_FEATURE_NEW_DASHBOARD=false

# ====================================
# Third-Party Services (Optional)
# ====================================

# Stripe public key
# Get from: https://dashboard.stripe.com/apikeys
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=

# Stripe secret key (server-side only)
# WARNING: NEVER commit this to version control
STRIPE_SECRET_KEY=
```

**Why good:** Grouped related variables for easy navigation, comments explain purpose and format reducing onboarding friction, example values show expected format, links to third-party services speed up setup

### Bad Example - Poor .env.example

```bash
# .env.example

NEXT_PUBLIC_API_URL=
DATABASE_URL=
STRIPE_SECRET_KEY=
```

**Why bad:** No comments explaining purpose or format, no grouping makes it hard to find related variables, no example values leaving developers guessing, no links to get third-party keys

# Security and Secrets Management

> Patterns for secure secret handling. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for essential patterns.

**Related Examples:**

- [core.md](core.md) - Per-app .env, Zod validation
- [naming-and-templates.md](naming-and-templates.md) - Framework prefixes, .env.example
- [feature-flags-and-config.md](feature-flags-and-config.md) - Feature flags, centralized config

---

## Secret Management

### Good Example - Comprehensive .gitignore

```gitignore
# .gitignore

# Environment files
.env.local
.env.*.local

# Optional: ignore all .env files except example
# .env
# !.env.example

# Sensitive files
*.key
*.pem
*.p12
*.pfx
```

**Why good:** `.env.local` and `.env.*.local` patterns prevent committing local secrets, sensitive file extensions (`*.key`, `*.pem`) prevent accidental key commits, optional .env ignore with `!.env.example` allows flexibility

### Bad Example - Secrets committed to repository

```bash
# .env (committed with actual secrets)
DATABASE_URL=postgresql://admin:SuperSecret123@prod.example.com:5432/mydb
STRIPE_SECRET_KEY=sk_live_actual_secret_key
JWT_SECRET=my-production-jwt-secret

# Committed to git = security breach!
```

**Why bad:** Committing secrets to git exposes them permanently in history, anyone with repo access can extract production credentials, secret rotation requires coordinating with all developers

---

## Secret Distribution Patterns

### Good Example - CI/CD Secret Management

```yaml
# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
        run: |
          # Secrets available as environment variables
          npm run deploy
```

**Why good:** Secrets stored in CI/CD provider (GitHub Secrets, Vercel), never committed to repository, access controlled by repository permissions, easy to rotate without code changes

### Bad Example - Sharing secrets via chat

```
# Slack message (NEVER DO THIS)
Hey team, here's the database password: SuperSecret123
Just copy it into your .env file
```

**Why bad:** Secrets in chat logs are permanent and searchable, no access control or audit trail, impossible to rotate without coordinating with everyone, violates security compliance requirements

---

## Secret Rotation Checklist

When rotating secrets:

1. Generate new secret in the service dashboard
2. Update CI/CD secrets (GitHub, Vercel, etc.)
3. Deploy with new secret
4. Verify application works with new secret
5. Revoke old secret in service dashboard
6. Never store old secrets "just in case"

# T3 Env Pattern

> T3 Env (`@t3-oss/env-nextjs`, `@t3-oss/env-core`) provides type-safe environment variables with client/server separation. See [SKILL.md](../SKILL.md) for core concepts.

**Related Examples:**

- [core.md](core.md) - Basic Zod validation pattern
- [naming-and-templates.md](naming-and-templates.md) - Framework prefixes, .env.example
- [security-and-secrets.md](security-and-secrets.md) - Secret management

---

## T3 Env for Next.js

### Good Example - T3 Env with Next.js

```typescript
// app/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  // Server-side variables (never exposed to client)
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET_KEY: z.string().min(1),
    STRIPE_SECRET_KEY: z.string().min(1),
  },

  // Client-side variables (embedded in bundle)
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().min(1),
    // Use z.stringbool() for boolean env vars (Zod 4+)
    NEXT_PUBLIC_ENABLE_ANALYTICS: z.stringbool().default(false),
  },

  // Explicit runtime env mapping (required for tree-shaking)
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    API_SECRET_KEY: process.env.API_SECRET_KEY,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY:
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
    NEXT_PUBLIC_ENABLE_ANALYTICS: process.env.NEXT_PUBLIC_ENABLE_ANALYTICS,
  },

  // Treat empty strings as undefined (recommended)
  emptyStringAsUndefined: true,
});
```

**Why good:** Separates client/server variables preventing accidental secret exposure, tree-shaking ensures only accessed vars included in bundle, emptyStringAsUndefined handles blank .env values correctly

---

## Build-Time Validation

### Good Example - Validate at build time via next.config

```typescript
// next.config.ts (Next.js 15+ - native TypeScript support, no jiti needed)
import "./app/env"; // Validates env vars at build time

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Your config here
};

export default nextConfig; // next.config requires default export
```

```typescript
// next.config.mjs (Next.js < 15, uses jiti for TypeScript)
import { fileURLToPath } from "node:url";
import createJiti from "jiti";

const jiti = createJiti(fileURLToPath(import.meta.url));

// Validate env vars at build time
jiti("./app/env");

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your config here
};

export default nextConfig; // next.config requires default export
```

**Why good:** Build fails immediately if env vars are missing or invalid, prevents deploying broken builds, catches configuration errors before runtime

---

## T3 Env for Vite

### Good Example - T3 Env Core with Vite

```typescript
// src/env.ts
import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  // Client-side variables (Vite uses VITE_ prefix)
  clientPrefix: "VITE_",

  client: {
    VITE_API_URL: z.string().url(),
    VITE_ENABLE_ANALYTICS: z.stringbool().default(false),
    VITE_ENVIRONMENT: z.enum(["development", "staging", "production"]),
  },

  // Server variables (build-time only in Vite)
  server: {
    // Vite doesn't expose non-prefixed vars to client
    API_SECRET: z.string().min(1).optional(),
  },

  runtimeEnv: import.meta.env,

  emptyStringAsUndefined: true,
});
```

**Why good:** Uses Vite's VITE\_ prefix convention, works with import.meta.env, type-safe access throughout app

---

## Skip Validation for CI/Linting

### Good Example - Skip validation when env vars not needed

```typescript
// app/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },

  // Skip validation for linting/type-checking in CI
  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
});
```

**Why good:** Allows running type checks and linting in CI without setting all env vars, controlled via SKIP_ENV_VALIDATION flag, still validates in actual builds/runtime

---

## Custom Error Handling

### Good Example - Custom validation error handler

```typescript
// app/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },

  // Custom error handler for validation failures
  onValidationError: (error) => {
    console.error("Invalid environment variables:");
    console.error(error.flatten().fieldErrors);
    throw new Error("Invalid environment configuration");
  },

  // Custom handler for accessing server vars on client
  onInvalidAccess: (variable) => {
    throw new Error(
      `Attempted to access server-side env var "${variable}" on the client`,
    );
  },
});
```

**Why good:** Custom error messages improve debugging, onInvalidAccess prevents silent failures when server vars accessed on client

---

## Type-Safe Usage

```typescript
// Any file in your app
import { env } from "~/env"; // Same import everywhere

// Server-side (API routes, server components, etc.)
const dbUrl = env.DATABASE_URL; // string - type-safe!

// Client-side (client components, hooks, etc.)
const apiUrl = env.NEXT_PUBLIC_API_URL; // string - type-safe!

// Accessing server var on client throws error at runtime
const secret = env.DATABASE_URL; // Error: Can't access server var on client
```

---

## Anti-Patterns

### Bad Example - Manual process.env access

```typescript
// components/api-client.ts - WRONG!
const apiUrl = process.env.NEXT_PUBLIC_API_URL; // No type safety!
const timeout = Number(process.env.NEXT_PUBLIC_TIMEOUT); // Could be NaN!
```

**Why bad:** No validation, no type safety, silent failures at runtime

### Bad Example - Missing runtimeEnv mapping

```typescript
// app/env.ts - WRONG!
export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  // Missing runtimeEnv - Next.js won't include the var in bundle!
});
```

**Why bad:** Next.js tree-shakes unused process.env access, missing runtimeEnv means vars are undefined at runtime