# @hivegrid/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.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 | | `WEB_RUNTIME_SURFACE` | production-only | web | code-and-example | | `PORTAL_SESSION_SECRET` | production-only | web | code-and-example | | `PORTAL_APP_HOST` | production-only | web, worker | 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 | | `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 | | `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.