home / skills / andrelandgraf / fullstackrecipes / env-management

env-management skill

This skill provides type-safe environment variable management with Zod validation, Vercel workflow integration, and prebuild checks for reliable deployments.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill env-management

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: env-management
description: Complete environment variable management with type-safe validation, Vercel dev workflow, and prebuild validation.
---

# Environment Variable Management

Complete environment variable management with type-safe validation, Vercel dev workflow, and prebuild validation.

## Cookbook - Complete These Recipes in Order

### Type-Safe Environment Configuration

Type-safe environment variable validation using Zod with a Drizzle-like schema API. Supports server/public fields, feature flags, either-or constraints, and client-side protection.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/config-schema-setup
```

### Environment Variable Management with Vercel

Manage environment variables across Vercel environments. Sync with Vercel CLI, handle local overrides, and load env vars in scripts.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/env-workflow-vercel
```

### Build-Time Environment Variable Validation

Validate environment variables on server start and before builds. Catch missing or invalid variables early with clear error messages.

```bash
curl -H "Accept: text/markdown" https://fullstackrecipes.com/api/recipes/env-validation
```

Overview

This skill provides complete environment variable management for TypeScript full-stack apps, combining type-safe validation, a Vercel-friendly development workflow, and prebuild validation. It bundles production-ready patterns and step-by-step recipes to ensure environment configuration is safe, predictable, and easy to operate across local, CI, and Vercel environments.

How this skill works

It uses a Zod-based, Drizzle-like schema API to declare typed environment shapes, including server-only, public, and feature-flag fields, and either-or constraints. The skill includes tooling to sync and manage variables with the Vercel CLI, load local overrides during development, and run validation at server start and before builds to surface missing or invalid values with clear errors.

When to use it

When you need type-safe runtime access to environment variables in a TypeScript app.
When deploying to Vercel and you want a repeatable sync and dev workflow for env vars.
When you want to catch misconfigured or missing env vars before runtime or during CI builds.
When you require client-side protection for secret values and explicit public variable handling.
When implementing feature flags or conditional either-or configuration constraints.

Best practices

Declare a single schema for all env variables with explicit server/public annotations.
Validate env vars on server start and add a prebuild validation step in CI to fail fast.
Keep local .env overrides only for development and sync canonical values to Vercel via CLI.
Use either-or constraints for mutually exclusive settings and document fallback rules.
Expose only whitelisted public variables to the client and treat others as server-only secrets.

Example use cases

A Next.js + TypeScript app that validates API keys and database URLs at startup and fails CI builds early when missing.
A Vercel-deployed service where env vars are managed via the Vercel CLI and local development uses safe overrides.
Feature-flag driven releases where flags are validated and typed, preventing accidental client exposure.
A monorepo with multiple services sharing a unified env schema and per-service overrides.
Prebuild scripts that run env validation to prevent broken production builds due to invalid configuration.

FAQ

How does this prevent secrets from leaking to the client?

The schema explicitly marks variables as server-only or public. Only fields marked public are exposed to client bundles, and tooling enforces that server-only values are never included in client-side builds.

Can I run validation during CI and local dev?

Yes. Validation runs at server start and can be added as a prebuild step in CI. Local development can use safe .env overrides while still validating against the canonical schema.