Add Environment Variable

Adds a new environment variable with Zod validation. All environment variables must be defined in src/env.ts and documented in .env.example.

Quick Reference

Files to modify:

1. src/env.ts - Add to schema and mapping
2. .env.example - Document the variable
3. tests/env.test.ts - Add validation tests

Instructions

Step 1: Add to Schema in src/env.ts

Add the variable to the envSchema object:

typescript
1const envSchema = z.object({
2  // ... existing variables ...
3
4  // Your new variable (with comment explaining purpose)
5  NEW_VARIABLE: z.string(), // Required string
6  // OR
7  NEW_VARIABLE: z.string().optional(), // Optional string
8  // OR
9  NEW_VARIABLE: z.string().default("default-value"), // With default
10  // OR
11  NEW_VARIABLE: z.coerce.number().default(3000), // Number with coercion
12  // OR
13  NEW_VARIABLE: z.string().url(), // URL validation
14});

Step 2: Add to Mapping Object

Add the variable to mappedEnv using the getEnv() helper (which reads prefixed variables):

typescript
1const mappedEnv = {
2  // ... existing mappings ...
3  NEW_VARIABLE: getEnv("NEW_VARIABLE"),
4};

Step 3: Document in .env.example

Add the variable with a descriptive comment, using the prefix (default: BT_):

bash
1# Description of what this variable is for
2BT_NEW_VARIABLE=example-value

Note: The prefix is defined in src/env.ts as const PREFIX = "BT". Change this when creating a new service from the template.

Step 4: Add Tests in tests/env.test.ts

Add test cases for the new variable:

typescript
1it("accepts valid NEW_VARIABLE", () => {
2  const parsed = envSchema.parse({ NEW_VARIABLE: "valid-value" });
3  expect(parsed.NEW_VARIABLE).toBe("valid-value");
4});
5
6it("defaults NEW_VARIABLE if missing", () => {
7  const parsed = envSchema.parse({});
8  expect(parsed.NEW_VARIABLE).toBe("default-value");
9});
10
11// OR for optional
12it("accepts missing NEW_VARIABLE", () => {
13  const parsed = envSchema.parse({});
14  expect(parsed.NEW_VARIABLE).toBeUndefined();
15});
16
17// OR for required
18it("rejects missing NEW_VARIABLE", () => {
19  expect(() => envSchema.parse({})).toThrow();
20});

Common Patterns

All examples use the getEnv() helper and BT_ prefix:

Required String

typescript
1// Schema
2MY_API_KEY: z.string(),
3
4// Mapping
5MY_API_KEY: getEnv("MY_API_KEY"),
6
7// .env.example
8BT_MY_API_KEY=your-api-key-here

Optional String

typescript
1// Schema
2OPTIONAL_FEATURE: z.string().optional(),
3
4// Mapping
5OPTIONAL_FEATURE: getEnv("OPTIONAL_FEATURE"),
6
7// .env.example
8# Optional: Enable feature X
9# BT_OPTIONAL_FEATURE=enabled

String with Default

typescript
1// Schema
2LOG_LEVEL: z.string().default("info"),
3
4// Mapping
5LOG_LEVEL: getEnv("LOG_LEVEL"),
6
7// .env.example
8BT_LOG_LEVEL=info

Number with Coercion

typescript
1// Schema
2RATE_LIMIT: z.coerce.number().default(100),
3
4// Mapping
5RATE_LIMIT: getEnv("RATE_LIMIT"),
6
7// .env.example
8BT_RATE_LIMIT=100

URL Validation

typescript
1// Schema
2WEBHOOK_URL: z.string().url().optional(),
3
4// Mapping
5WEBHOOK_URL: getEnv("WEBHOOK_URL"),
6
7// .env.example
8# Webhook endpoint for notifications
9BT_WEBHOOK_URL=https://example.com/webhook

Enum Values

typescript
1// Schema
2NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
3
4// Mapping
5NODE_ENV: getEnv("NODE_ENV"),
6
7// .env.example
8BT_NODE_ENV=development

Boolean (as string)

typescript
1// Schema
2ENABLE_FEATURE: z.string().transform(v => v === "true").default("false"),
3
4// Mapping
5ENABLE_FEATURE: getEnv("ENABLE_FEATURE"),
6
7// .env.example
8BT_ENABLE_FEATURE=false

Usage in Code

Always import from @/env, never use process.env directly:

typescript
1import { env } from "@/env";
2
3// Correct
4const apiKey = env.MY_API_KEY;
5
6// Wrong - bypasses validation
7const apiKey = process.env.MY_API_KEY;

Full Example: Adding Email Service Config

1. Update src/env.ts

typescript
1const envSchema = z.object({
2  // ... existing ...
3
4  // Email service configuration
5  EMAIL_API_KEY: z.string().optional(),
6  EMAIL_FROM_ADDRESS: z.string().email().optional(),
7  EMAIL_PROVIDER: z.enum(["sendgrid", "mailgun"]).default("sendgrid"),
8});
9
10const mappedEnv = {
11  // ... existing ...
12  EMAIL_API_KEY: getEnv("EMAIL_API_KEY"),
13  EMAIL_FROM_ADDRESS: getEnv("EMAIL_FROM_ADDRESS"),
14  EMAIL_PROVIDER: getEnv("EMAIL_PROVIDER"),
15};

2. Update .env.example

bash
1# Email service configuration
2BT_EMAIL_API_KEY=your-email-api-key
3BT_EMAIL_FROM_ADDRESS=noreply@example.com
4BT_EMAIL_PROVIDER=sendgrid

3. Update tests/env.test.ts

typescript
1it("accepts valid email configuration", () => {
2  const parsed = envSchema.parse({
3    EMAIL_API_KEY: "test-key",
4    EMAIL_FROM_ADDRESS: "test@example.com",
5    EMAIL_PROVIDER: "mailgun",
6  });
7  expect(parsed.EMAIL_API_KEY).toBe("test-key");
8  expect(parsed.EMAIL_FROM_ADDRESS).toBe("test@example.com");
9  expect(parsed.EMAIL_PROVIDER).toBe("mailgun");
10});
11
12it("defaults EMAIL_PROVIDER to sendgrid", () => {
13  const parsed = envSchema.parse({});
14  expect(parsed.EMAIL_PROVIDER).toBe("sendgrid");
15});
16
17it("rejects invalid EMAIL_FROM_ADDRESS", () => {
18  expect(() =>
19    envSchema.parse({ EMAIL_FROM_ADDRESS: "not-an-email" }),
20  ).toThrow();
21});
22
23it("rejects invalid EMAIL_PROVIDER", () => {
24  expect(() => envSchema.parse({ EMAIL_PROVIDER: "invalid" })).toThrow();
25});

What NOT to Do

• Do NOT use process.env directly in application code
• Do NOT forget to add the mapping in mappedEnv
• Do NOT skip documenting in .env.example
• Do NOT skip adding tests for validation rules
• Do NOT store secrets in .env.example (use placeholder values)

See Also

• create-utility-service - Services that use environment config
• test-schema - Testing Zod schemas (similar patterns)