@toolctrl/config
Typed environment catalog and lightweight validation helpers for the apps/web, apps/api and apps/worker runtime split.
This package is now partially wired into runtime loaders for web/API/worker configuration and remains the source of truth for env examples and documentation drift checks. Catalog entries should describe whether a key is required for core boot, required by a specific app, optional for an enabled provider, platform-supplied, or deprecated.
Classification
required-core: needed for the current app to boot safely.required-per-app: required by at least one target app or API path.optional-provider: only required when the related integration is enabled.local-development-only: local convenience variables.production-only: supplied by production/runtime platforms or only useful in production.deprecated-remove: present in examples but not currently backed by active code usage.
Current Inventory
The catalog is verified against .env.example, .env.local.example, .env.production.example, .env.fly.example, .env.test, Prisma env(...) usage, and active web/API/worker/package environment reads.
| Variable | Classification | Targets | Source |
|---|---|---|---|
APP_NAME |
required-core | shared, web, api, worker | code-and-example |
DATABASE_URL |
required-core | shared, web, api, worker | code-and-example |
SESSION_SECRET |
required-core | web, api | code-and-example |
CRYPTO_SECRET |
required-per-app | web, api | code-and-example |
API_ACCESS_TOKEN |
required-per-app | web, api | code-and-example |
JWT_SECRET |
required-per-app | web, api | code-and-example |
ANALYTICS_TOKEN |
required-per-app | api | code |
NODE_ENV |
production-only | shared, web, api, worker | runtime |
APP_REVISION |
production-only | shared, web, api, worker | runtime |
DIRECT_URL |
production-only | shared, web, api, worker | code |
SERVER_URL |
production-only | web, api | code |
VERCEL_URL |
production-only | web | code |
WEBHOOKS_URL |
optional-provider | web, api | code-and-example |
SUPABASE_API_URL |
optional-provider | web, api | code-and-example |
SUPABASE_KEY |
optional-provider | web, api | code-and-example |
STRIPE_SK |
optional-provider | web, api | code-and-example |
STRIPE_WEBHOOK_SIGNING_SECRET |
optional-provider | web, api | code-and-example |
STRIPE_ACCOUNT_COUNTRY |
production-only | web, api | example |
MAILJET_API_KEY |
optional-provider | web, api, worker | code-and-example |
MAILJET_FROM_EMAIL |
optional-provider | web, api, worker | code-and-example |
MAILJET_FROM_NAME |
optional-provider | web, api, worker | example |
MAILJET_SECRET_KEY |
production-only | web, api, worker | example |
SUPPORT_EMAIL |
optional-provider | web | example |
COMPANY_NAME |
optional-provider | web, api | example |
COMPANY_ADDRESS |
optional-provider | web, api | example |
INTEGRATIONS_CONTACT_FORMSPREE |
optional-provider | web | code-and-example |
CONVERTKIT_APIKEY |
optional-provider | web | code-and-example |
CONVERTKIT_FORM |
optional-provider | web | code-and-example |
CONVERTKIT_API_SECRET |
optional-provider | web | code |
CRISP_CHAT_WEBSITE_ID |
optional-provider | web | code-and-example |
ANALYTICS_GA_TRACKING_ID |
optional-provider | web | code-and-example |
GITHUB_OAUTH_CLIENT_ID |
optional-provider | web, api | code-and-example |
GITHUB_OAUTH_CLIENT_SECRET |
optional-provider | web, api | code-and-example |
AUTH_MAGIC_LINK_ENABLED |
optional-provider | web, api | code-and-example |
AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES |
optional-provider | web, api | code-and-example |
AUTH_RECAPTCHA_SITE_KEY |
optional-provider | web | code-and-example |
NOTIFICATIONS_NOVU_API_KEY |
optional-provider | web | code-and-example |
MISTRAL_API_KEY |
optional-provider | web, api, worker | code-and-example |
AI_PROCESSING_REGION |
production-only | web, api, worker | example |
MISTRAL_MODEL |
optional-provider | web, api, worker | code-and-example |
SCALEWAY_API_KEY |
optional-provider | web, api, worker | code-and-example |
SCALEWAY_MODEL |
optional-provider | web, api, worker | code-and-example |
SCALEWAY_BASE_URL |
optional-provider | web, api, worker | code-and-example |
SCALEWAY_REGION |
production-only | web, api, worker | example |
ALEPH_ALPHA_API_KEY |
optional-provider | web, api, worker | code-and-example |
ALEPH_ALPHA_MODEL |
optional-provider | web, api, worker | code-and-example |
ALEPH_ALPHA_BASE_URL |
optional-provider | web, api, worker | code-and-example |
IMPORT_QUEUE_ENABLED |
optional-provider | web, worker | code-and-example |
BULLMQ_REDIS_URL |
optional-provider | web, api, worker | code-and-example |
BROWSER_RUNTIME_URL |
optional-provider | api, worker | example |
BROWSER_RUNTIME_API_KEY |
optional-provider | api, worker | example |
BROWSER_SESSION_TIMEOUT_MS |
optional-provider | api, worker | example |
IPSTACK_API_KEY |
optional-provider | api, worker | code |
IPAPIIS_API_KEY |
optional-provider | api, worker | code |
PORTAL_SERVER_URL |
optional-provider | web, api | code-and-example |
PORTAL_SERVER_FLY_TOKEN |
optional-provider | web, api, worker | code-and-example |
DEMO_USER |
local-development-only | web | code |
SEED_ADMIN_EMAIL |
production-only | web | code-and-example |
SEED_ADMIN_PASSWORD |
production-only | web | code-and-example |
SEED_DEMO_DATA |
local-development-only | web | code-and-example |
ALLOW_STAGING_DEMO_SEED |
production-only | web | code |
SITE_KEY_* |
optional-provider | api | dynamic |
Mail Provider Scope
Mailjet is the transactional runtime default. MAILJET_API_KEY, MAILJET_FROM_EMAIL, and MAILJET_FROM_NAME configure standard outbound transactional delivery.