Env Config Manager

---
name: env-config-manager
description: |
  Trigger when the user asks to manage env vars, validate config, set up
  .env files, or enforce typed env access. Phrases: "env vars", ".env file",
  "config management", "type-safe env", "missing env var".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# Env Config Manager

Set up type-safe, validated env var access so the app fails at startup
when a required var is missing instead of at the first request.

## Prerequisites

- Node, Next.js, or similar project
- Runtime env access available (process.env)

## Steps

1. **Install a validator.** `zod` + `@t3-oss/env-nextjs` for Next.js, or
   bare zod for others.

2. **Define the schema.** Separate server-only from client-exposed:
   ```ts
   import { createEnv } from "@t3-oss/env-nextjs";
   import { z } from "zod";

   export const env = createEnv({
     server: {
       DATABASE_URL: z.string().url(),
       STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
       CRON_SECRET: z.string().min(32),
     },
     client: {
       NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
     },
     runtimeEnv: {
       DATABASE_URL: process.env.DATABASE_URL,
       STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
       CRON_SECRET: process.env.CRON_SECRET,
       NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
     },
   });
   ```

3. **Import env only, never process.env.** Grep the codebase for
   `process.env` and replace with the typed export.

4. **Keep .env.local.example in sync.** Every key in the zod schema should
   have a placeholder entry. CI should fail if the schema has a key missing
   from the example file.

5. **Separate dev and prod constraints.** Some vars are optional in dev
   but required in prod. Use a `z.string().optional()` with a runtime check
   that asserts presence when `NODE_ENV === 'production'`.

6. **Never commit the real .env.** `.env.local` in .gitignore. Only the
   example file is tracked.

## Common mistakes

- Reading a client-side env var server-side or vice versa. `NEXT_PUBLIC_*`
  ends up in the client bundle; everything else does not.
- Defaulting a required secret to an empty string (`process.env.FOO || ""`).
  Silent failures are worse than loud startup errors.
- Putting secrets in the example file as defaults. The template should
  have clear placeholders like `sk_test_replace_me`.

## Output

- Typed env export module
- `process.env` references replaced
- Updated .env.local.example
- Startup validation test ensuring boot fails on missing vars