@types for your env vars

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';
import { secrets as openai } from '@secretdef/openai';

export const secrets = defineSecrets({
  ...openai,
  DATABASE_URL: {
    description: 'Postgres connection string',
    dashboard: 'https://console.neon.tech',
    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 defined 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.

Dashboard UI

See all your secrets at a glance. One command.

This is a preview — run npx secretdef ui for the real thing.

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 + useSecret()

import OpenAI from 'openai';
import { useSecret } from 'secretdef';
import '@secretdef/openai';

// useSecret() throws a rich error if OPENAI_API_KEY is missing
const openai = new OpenAI({ apiKey: useSecret('OPENAI_API_KEY') });

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 it. Your agent reads the same output and knows exactly what to do.

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
//     Defined in:           src/secrets.ts
//     Current environment:  development
//     To fix: set STRIPE_SECRET_KEY in your environment or .env file.
//
// vs: TypeError: Cannot read properties of undefined

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 1,319+ ready-made @secretdef/* packages. Here are some popular ones:

Native integrations

These libraries ship their own defineSecrets() calls natively — just install and import, no @secretdef/* package needed.

1,319 community packages

Every service below has a ready-made @secretdef/* package you can install today. Each one declares the environment variables the service needs — descriptions, dashboard links, and validation rules included.

Zero dependencies. ~2KB. MIT licensed.