Skip to content
Skills Library
Programming · Building & coding

validate-env

/validate-env

Use when a frontend project reads import.meta.env - parses it once with a Zod schema at startup, fails fast with a readable message, and exports a typed env object the seams import instead of raw reads.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a frontend project reads import.meta.env - parses it once with a Zod schema at startup, fails fast with a readable message, and exports a typed env object the seams import instead of raw reads.

Original author description

Use when a frontend project reads import.meta.env - parses it once with a Zod schema at startup, fails fast with a readable message, and exports a typed env object the seams import instead of raw reads.

How it works

  1. 1. Audit current state
  2. 2. Decide what to do
  3. 3. Detect framework
  4. 4. Install (if needed)
  5. 5. Schema, parsed once at startup
  6. 6. Migrate the seams
  7. 7. Verify
  8. References
Original SKILL.md headings · 107 lines, 652 words
SKILL.md preview
---
name: validate-env
description: Use when a frontend project reads import.meta.env - parses it once with a Zod schema at startup, fails fast with a readable message, and exports a typed env object the seams import instead of raw reads.
---

# Validate Env

## 1. Audit current state

```bash
ls src/libs/env.ts .env.example .env.test .claude/stack-profile.md 2>/dev/null
grep -rn "import.meta.env.VITE_" src/ 2>/dev/null | head   # raw, unvalidated reads to migrate
grep -n '"zod"' package.json
```

Read `.claude/stack-profile.md` if present: `package_manager` replaces `pnpm` below; `frontend.meta` of `nuxt` or `next` means this skill does not apply (their env comes from `runtimeConfig` / `NEXT_PUBLIC_*`, validated in their own config); say so and stop.

A missing `VITE_API_URL` today fails *silently at runtime* (the `fetcher` falls back to `''` and every request hits the page origin). This skill turns that into a startup error.

## 2. Decide what to do
- No `env.ts` → create it (steps 4–6) and migrate raw reads (step 6).
- `env.ts` exists → confirm the schema covers every `VITE_*` the app reads.
- The app reads **no** `VITE_*` variable yet → exit; add the skill with the first one.

## 3. Detect framework
None needed: Vite exposes `import.meta.env` the same way to React and Vue.

## 4. Install (if needed)
```bash
pnpm add zod
```
Zod 4 (`z.url()`, `z.prettifyError()`). Zod 3 projects: keep their API, do not mix.

## 5. Schema, parsed once at startup

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

// A blank `VITE_X=` in .env or CI arrives as '' — treat it as unset.
const blankToUndefined = (value: unknown) => (value === '' ? undefined : value);
const httpUrl = z.url({ protocol: /^https?$/ });

const schema = z.object({
  VITE_API_URL: httpUrl,
  VITE_SENTRY_DSN: z.preprocess(blankToUndefined, httpUrl.optional()),
  VITE_ANALYTICS_DOMAIN: z.preprocess(blankToUndefined, z.string().min(1).optional()),
});

const parsed = schema.safeParse(import.meta.env);
if (!parsed.success) {
  throw new Error(`Invalid environment variables:\n${z.prettifyError(parsed.error)}`);
}

/** Validated, typed env. Import this; never read `import.meta.env.VITE_*` directly. */
export const env = parsed.data;
```

Importing `env.ts` anywhere (the seams do) runs the check before the app renders, so a bad deploy fails at boot with the field name, not later with an empty-URL fetch. Keep only the variables the app reads; add a line when a seam needs one (`set-up-realtime` adds `VITE_REALTIME_URL`).

`env`'s type comes from the schema, so there is no second declaration to keep in sync. Do **not** add an `ImportMetaEnv` augmentation: raw reads are banned, so it would only duplicate the schema.

Commit a `.env.example` listing every key with a harmless value, and a `.env.test` with the values Vitest needs (`VITE_API_URL=http://api.test`); Vitest loads `.env.test` because it runs in Vite's `test` mode.

## 6. Migrate the seams

Point each seam at `env`:
```ts
// src/libs/fetcher.ts
import { env } from '@/libs/env';
const BASE_URL = env.VITE_API_URL; // was: import.meta.env.VITE_API_URL ?? ''
```
Do the same in `sentry.ts` (`env.VITE_SENTRY_DSN`) and `analytics.ts` (`env.VITE_ANALYTICS_DOMAIN`).

## 7. Verify

Add the unit test; it proves the check can fail:
```ts
// tests/unit/env.test.ts (needs configure-test-stack and the `@/` alias from configure-typescript; otherwise run the two checks by hand)
import { afterEach, expect, test, vi } from 'vitest';

afterEach(() => {
  vi.unstubAllEnvs();
  vi.resetModules();
});

test('accepts a valid environment and treats blank optionals as unset', async () => {
  vi.stubEnv('VITE_API_URL', 'https://api.example.com');
  vi.stubEnv('VITE_SENTRY_DSN', '');
  const { env } = await import('@/libs/env');
  expect(env.VITE_SENTRY_DSN).toBeUndefined();
});

test('throws at import time with the field name when a variable is invalid', async () => {
  vi.stubEnv('VITE_API_URL', 'javascript:alert(1)');
  await expect(import('@/libs/env')).rejects.toThrow(/VITE_API_URL/);
});
```
`vi.stubEnv` reaches `import.meta.env` only on Vitest versions whose env replacement forwards `process.env` (Vitest 3+); on an older runner the test reads `.env.test` instead, so the "throws" case may not throw. If that happens, assert against the parse function directly instead of the module import.
```bash
pnpm typecheck                 # env is typed from the schema
pnpm vitest run tests/unit/env.test.ts
grep -rn "import.meta.env.VITE_" src/   # only src/libs/env.ts may match
# by hand: blank VITE_API_URL in .env, `pnpm dev` → the console shows "Invalid environment variables: ✖ Invalid URL → at VITE_API_URL"
```

## References
- ./env-patterns.md — fail-fast, one typed object, the `VITE_` prefix, shape not presence, blank values, build-time secrets.
- ../_shared/fetcher.md — the `fetcher` seam that imports `env`.
- ../_shared/conventions.md — `libs/` seam location, the `typecheck` rule.
Files in this package (2)
  • SKILL.md 5 KB
  • env-patterns.md 4 KB

Versions

The database has no other skills named validate-env.

Database snapshot: 13.11.2026 · package version 19f2324a214e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100output-error-zod-import
    Fix Zod schema import issues in Output SDK workflows. Use when seeing "incompatible schema" errors, type errors at step boundaries, schema validation failures, or when schemas don't match between steps.
  • 100dynamic-config-management
    Manage application configuration—schemas, validation, .env.example, placeholder detection, fail-fast startup. Use when adding env vars or centralizing config. Triggers: "config", "environment variables", ".env", "settings", "fail fast", "config schema".
  • 100astro-env
    ACTIVATE when working with environment variables, feature flags, or runtime configuration in Astro. ACTIVATE for 'import.meta.env', '.env', 'PUBLIC_', 'feature flag'. Covers: server vs client variables (PUBLIC_ prefix), feature flags pattern with centralized config, TypeScript…
  • 100dynamic-config-management
    Manage application configuration—schemas, validation, .env.example, placeholder detection, fail-fast startup. Use when adding env vars or centralizing config.
  • 100zod
    Zod is a TypeScript-first schema library that validates data at runtime and infers static types from the same schema. Use when validating API request bodies, form input, environment variables or config files, parsing untrusted JSON, or migrating from Zod 3 to Zod 4. Covers…
  • 100env-setup-wizard
    Set up environment variables, .env files, and configuration management. Use when configuring environment variables, creating .env files, or managing app configuration.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.