home / skills / forge-town / skills / zod-env-integration

zod-env-integration skill

safe

This skill generates type-safe Zod based environment variable management code from .env.example, including schemas, getters, and barrels for clean imports.

npx playbooks add skill forge-town/skills --skill zod-env-integration

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

Files (13)

SKILL.md

2.0 KB

---
name: zod-env-integration
description: Generate Zod-based environment variable management code from .env.example files. Use when you need to create type-safe env management, standardize env handling, or generate env schemas.
---

# Zod 环境变量集成

提供生成基于 Zod 验证的类型安全环境变量管理代码的指导和模板。包含创建 schema、getter 函数和桶导出的示例和最佳实践。

## 工作原理

1. 在项目根目录准备 .env.example 文件
2. **严格参照** [best-practice-examples/](best-practice-examples/) 中的代码结构和模式
3. 对于单环境：生成 `integrations/env/` 包含 schema、getter 和导出
4. 对于多环境：为每个环境生成独立的 `integrations/{env}-env/` 目录
5. 按照代码生成指南创建 Zod schema
6. 实现带有适当错误处理的 getter 函数
7. 创建桶导出以实现干净的导入
8. 在应用程序中使用生成的代码

## 使用方法

此技能提供文档和示例。按照参考指南中的步骤操作：

- [单环境代码生成指南](references/single-env-guide.md) - 单环境代码生成的详细规则
- [多环境代码生成指南](references/multi-env-guide.md) - 多环境代码生成的详细规则
- [.env.example 模板](references/.env.example.template) - .env 文件的模板
- [最佳实践示例](best-practice-examples/) - **必须严格参照的**单环境和多环境代码示例

**重要：** 实现时必须严格遵循 best-practice-examples 中的代码结构、命名约定和错误处理模式。任何修改都可能破坏类型安全保证。

## 故障排除

- **缺少 .env.example**：从 references/.env.example.template 复制模板
- **未安装 Zod**：在项目中运行 `pnpm install zod`
- **类型错误**：检查代码生成指南中的正确 schema 语法
- **导入错误**：确保 index.ts 中的桶导出正确
- **偏离最佳实践**：如果遇到问题，首先确认代码结构是否严格遵循 best-practice-examples 中的模式

Overview

This skill generates TypeScript code that manages environment variables using Zod schemas for type-safe validation. It converts a .env.example into a consistent set of schema files, getter functions, and barrel exports to standardize env handling across single- and multi-environment projects. The output enforces naming, structure, and error handling patterns to preserve compile-time guarantees.

How this skill works

The skill reads your .env.example and creates Zod schemas that mirror each variable and its expected type. It emits a small integration package (integrations/env/ for single env or integrations/{env}-env/ for each environment) including schema definitions, runtime getters with robust error messages, and a barrel export for clean imports. The generator follows strict patterns from the best-practice examples so the produced code is predictable and type-safe.

When to use it

You need type-safe environment variable access in a TypeScript codebase.
You want to standardize env handling across multiple services or environments.
You have a .env.example and want automatic Zod schema generation.
You need consistent error reporting and runtime validation for env values.

Best practices

Keep a canonical .env.example at the project root and update it with new variables.
Follow the naming and folder conventions exactly (integrations/{env}-env or integrations/env).
Define precise Zod types (string, number, boolean, enums) rather than lax unions.
Use the generated getter functions instead of reading process.env directly.
Preserve the generated code structure; manual edits can break type guarantees.

Example use cases

Generate a single integrations/env package for a monorepo service.
Create separate integrations/staging-env and integrations/production-env for multi-environment deployments.
Rapidly onboard new projects by converting the project .env.example into validated schemas.
Enforce consistent runtime errors when required environment variables are missing or malformed.

FAQ

What happens if my .env.example is missing?

Copy the provided .env.example template into the project root, then run the generator; the template ensures required keys are present.

Do I need to install Zod manually?

Yes. Install Zod in the project (for example pnpm install zod) so the generated TypeScript can import and use it.