Validate environment variables on server start and before builds. Catch missing or invalid variables early with clear error messages.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Validate environment variables on server start and before builds. Catch missing or invalid variables early with clear error messages.
See:
env-validation in Fullstack RecipesSome environment variables are read internally by packages rather than passed as arguments. To catch missing variables early instead of at runtime, import your configs in instrumentation.ts:
// src/instrumentation.ts
import * as Sentry from "@sentry/nextjs";
import { sentryConfig } from "./lib/sentry/config";
// Validate required configs on server start
import "./lib/ai/config";
import "./lib/db/config";
export async function register() {
// ... initialization code
}
The side-effect imports trigger configSchema validation immediately when the server starts. If any required environment variable is missing, the server fails to start with a clear error rather than failing later when the code path is executed.
{% registry items="validate-env" /%}
Add the validation script to your package.json:
{
"scripts": {
"prebuild": "bun run env:validate:prod",
"env:validate": "bun run scripts/validate-env.ts --environment=development",
"env:validate:prod": "bun run scripts/validate-env.ts --environment=production"
}
}
Use the env:validate and env:validate:prod scripts to validate all your configs (config.ts files in src/lib/*/) against your .env files.
The prebuild script (configured above) runs automatically before build, ensuring environment variables are validated before every build (locally and in CI/Vercel). If validation fails, the build stops early with a clear error.
The script:
.env files using Next.js's loadEnvConfig (respects the same load order as Next.js)config.ts files in src/lib/*/configSchema validation.env files but not used by any configExample output with a validation error:
š Environment Configuration Validator
Environment: development
Loading environment files...
ā .env.local
ā .env.development
Found 5 config files:
ā src/lib/resend/config.ts
ā src/lib/sentry/config.ts
ā src/lib/db/config.ts
ā src/lib/ai/config.ts
ā src/lib/auth/config.ts
Validation Errors:
src/lib/resend/config.ts:
Configuration validation error for Resend!
Did you correctly set all required environment variables in your .env* file?
- server.fromEmail (FROM_EMAIL) must be defined.
Summary:
Configs validated: 4
Validation errors: 1
Unused env vars: 0
Example output with an unused variable:
š Environment Configuration Validator
Environment: development
Loading environment files...
ā .env.local
ā .env.development
Found 5 config files:
ā src/lib/resend/config.ts
ā src/lib/sentry/config.ts
ā src/lib/db/config.ts
ā src/lib/ai/config.ts
ā src/lib/auth/config.ts
Unused Environment Variables:
These variables are defined in .env files but not used by any config:
ā OLD_API_KEY
defined in: .env.local
Summary:
Configs validated: 5
Validation errors: 0
Unused env vars: 1
The script exits with code 1 if any validation errors occur (useful for CI), but unused variables only trigger warnings without failing the build.