Your app has secret dependencies. Declare them

How it works

You list the secrets your app needs — the env var name, a description, and where to get the value. At startup, one call checks everything and tells you exactly what's missing.

1.List what your app needs

// src/secrets.ts
import { defineSecrets } from 'secretdef';

export const secrets = defineSecrets({
  STRIPE_SECRET_KEY: {
    description: 'Stripe API secret key — https://dashboard.stripe.com/apikeys',
    example: 'sk_live_...',
    validate: 'str',
    devDefault: 'sk_test_placeholder',
  },
  DATABASE_URL: {
    description: 'Postgres connection string — format: postgresql://user:pass@host/db',
    validate: 'url',
    devDefault: 'postgresql://localhost:5432/myapp_dev',
  },
});

2.Validate at startup

// src/env.ts — validate everything at startup
import { validateSecrets } from 'secretdef';
import { secrets as app } from './secrets';
import { secrets as db } from './modules/db/secrets';

export const env = validateSecrets({
  ...app,
  ...db,
});

// Or use auto-register — less wiring, same result
import { validateSecrets } from 'secretdef';

import './secrets';
import './modules/db/secrets';

const env = validateSecrets();

3.Get actionable errors instead of cryptic crashes

Using a service? Just import its package.

Community @secretdef/* packages ship ready-made definitions for popular services. Install, import, done.

// app entry point
import { validateSecrets } from 'secretdef';

import '@secretdef/openai';
// import '@secretdef/stripe';
// import '@secretdef/resend';

// Validates ALL secrets registered by the imports above
validateSecrets();

That's it. All 7 OpenAI env vars — OPENAI_API_KEY, OPENAI_ORG_ID, and more — are now validated at startup with descriptions, dashboard links, and format hints.

Strict in prod. Flexible in dev.

secretdef adapts to the environment. You don't need every secret configured to start working locally.

Two lines. Fail at startup, not at 2am.

Most SDKs already read process.env internally. Add two lines and missing keys fail on server start — not when a user hits the code path.

Just import — zero config

import { Resend } from 'resend';
import '@secretdef/resend';

// That's it. validateSecrets() at your entry point
// catches missing RESEND_API_KEY at startup.
const resend = new Resend(process.env.RESEND_API_KEY);

Built for AI agents

Claude Code, Cursor, Codex, and Gemini CLI generate integrations fast — but crash on missing env vars with zero context. secretdef gives them structured errors they can read and act on.

Use the Quick start prompt above to add secretdef to any project with a single paste.

Every error tells you how to fix it

process.env.KEY returns undefined silently. useSecret('KEY') tells you what's wrong, where to find the value, and which file declared the requirement.

import { useSecret } from 'secretdef';

const key = useSecret('STRIPE_SECRET_KEY');
//
// If missing → throws with:
//   SecretNotAvailable: STRIPE_SECRET_KEY is not configured.
//     Environment variable: STRIPE_SECRET_KEY
//     Description:          Stripe API secret key
//     Where to find it:     https://dashboard.stripe.com/apikeys
//     To fix: set STRIPE_SECRET_KEY in your .env file.
//
// vs: TypeError: Cannot read properties of undefined

The descriptions you write show up verbatim in error output. A dashboard link and a format hint turn a debugging session into a copy-paste fix. These descriptions aren't just for humans — when Claude Code hits a missing secret, it reads this and knows exactly what to do.

Every module declares its secrets

Your database module knows it needs DATABASE_URL. Your payment code knows it needs a Stripe key. When each module ships secret definitions, the whole app's requirements become discoverable, validated, and documented — automatically.

For services that don't ship their own definitions yet, the community maintains ready-made @secretdef/* packages:

+7 more packages coming soon. Add yours

Zero-dependency. ~2KB. Works alongside Doppler, Vault, AWS Secrets Manager, or plain .env files.