mcpField
E
env-setup-wizard

env-setup-wizard

github.com/onewave-aiDevelopment393293 installsUpdated 1w ago
Repository

About env-setup-wizard

env-setup-wizard is a skill for organizing project environment variables, adding type-safe access and startup validation, and documenting configuration. It provides patterns for general projects and Next.js.

Key features

  1. 01Organize .env files by environment
  2. 02Generate a committed .env.example
  3. 03Validate variables with Zod
  4. 04Separate server and client variables
  5. 05Document secrets handling practices

Use cases

  1. 01Setting up environment configuration for a new project
  2. 02Adding startup checks for required variables
  3. 03Configuring server and client variables in Next.js

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/onewave-ai/claude-skills --skill env-setup-wizard

After installing, type/env-setup-wizardin Claude Code to confirm it loaded.

Details

From the project README

Environment Setup Wizard

Instructions

When setting up environment configuration:

  1. Identify required variables for the project
  2. Create .env structure with proper organization
  3. Set up type-safe access to env vars
  4. Add validation on startup
  5. Document all variables

File Structure

project/
├── .env                  # Local development (git-ignored)
├── .env.example          # Template (committed to git)
├── .env.local            # Local overrides (git-ignored)
├── .env.development      # Development defaults
├── .env.production       # Production defaults
└── src/
    └── lib/
        └── env.ts        # Type-safe env access

.env.example Template

# ===================
# Application
# ===================
NODE_ENV=development
APP_URL=http://localhost:3000
PORT=3000

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

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

# ===================
# Third-party APIs
# ===================
# Get from: https://stripe.com/dashboard
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

# Get from: https://resend.com
RESEND_API_KEY=

# ===================
# Storage
# ===================
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1
S3_BUCKET_NAME=

Type-Safe Environment (Zod)

// src/lib/env.ts
import { z } from 'zod';

const envSchema = z.object({
  // App
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  APP_URL: z.string().url(),
  PORT: z.coerce.number().default(3000),

  // Database
  DATABASE_URL: z.string().min(1),

  // Auth
  JWT_SECRET: z.string().min(32),
  NEXTAUTH_SECRET: z.string().min(32),
  NEXTAUTH_URL: z.string().url(),

  // APIs (optional in dev)
  STRIPE_SECRET_KEY: z.string().optional(),
  RESEND_API_KEY: z.string().optional(),
});

// Validate on import
const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('Invalid environment variables:');
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const env = parsed.data;

// Type export for use elsewhere
export type Env = z.infer<typeof envSchema>;

Next.js Specific

// src/lib/env.ts for Next.js
import { z } from 'zod';

// Server-side variables
const serverSchema = z.object({
  DATABASE_URL: z.string(),
  JWT_SECRET: z.string(),
});

// Client-side variables (must start with NEXT_PUBLIC_)
const clientSchema = z.object({
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_STRIPE_KEY: z.string(),
});

export const serverEnv = serverSchema.parse(process.env);
export const clientEnv = clientSchema.parse({
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  NEXT_PUBLIC_STRIPE_KEY: process.env.NEXT_PUBLIC_STRIPE_KEY,
});

T3 Env (Recommended for Next.js)

// src/env.mjs
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    NODE_ENV: z.enum(["development", "test", "production"]),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  },
});

.gitignore

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

# Keep example
!.env.example

Security Best Practices

  1. Never commit secrets to git
  2. Use different values per environment
  3. Rotate secrets regularly
  4. Use secret managers in production (Vault, AWS Secrets Manager)
  5. Validate on startup to fail fast
  6. Prefix client vars (NEXT_PUBLIC_, VITE_, REACT_APP_)

Comments

Markdown supported