Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/env
Single source of truth for all environment variable access. Validates at module load, separates server secrets from browser-safe values.
Always
- Import env constants from
@carbon/env(or@carbon/authwhich re-exports it) — never readprocess.envdirectly. - Declare a new variable once in
src/schema.ts(group, description,type,secret,browser,required,aliases), then export it fromsrc/index.tswithgetEnv("NAME").secret: truereads as""in the browser. - A
browser: truevariable must also be returned bygetBrowserEnv()— thesatisfiesthere fails typecheck until it is — AND added to each app's root-loaderenvobject. TheWindow.envtype is derived from the schema. validateEnvruns once at module load on the server and reports every problem together (formatReport).required: "error"stops startup;required: "warn", an invalid type and a half-configured feature are printed and become errors in the next release.- Rename a variable by adding the old name to the new one's
aliases; keep the old export as a@deprecatedconstant. - Tests are not validated (
VITEST); mock the module or stubprocess.env.SKIP_ENV_VALIDATION=1does the same for a script.
Ask First
- Adding a
required: "error"variable, or flipping"warn"to"error"— this changes boot requirements for every deployment. thedeployments-set-required-envcheck (@carbon/checks) must pass for each of them first. - Changing
getAppUrl()/getMESUrl()resolution logic — affects cross-app links across all editions.
Never
- Put ports, URLs, Supabase keys, or Redis/Inngest dev values in
.env—crbn upmanages those via.env.local. - Expose secret keys in
getBrowserEnv()— theisSecretguard only works forgetEnvcalls, not the browser env object. - Hand-edit
.env.local— it's generated bycrbn upand overwritten on each run.
Validation Commands
pnpm --filter @carbon/env typecheck
pnpm --filter @carbon/env test
Key Exports
src/schema.ts declares the variables, src/validate.ts checks and reports them, src/index.ts exports the values:
schema,validateEnv(source),formatReport(report)— the declaration and the startup reportgetEnv(name)— reads one schema variable (its own name, then its aliases)Deployment:
APP_URL(this app's origin; aliasVERCEL_URL),APP_ENV(aliasVERCEL_ENV, defaults toNODE_ENV)Database / Supabase:
DATABASE_URL(aliasSUPABASE_DB_URL),SUPABASE_URL,SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEY,SUPABASE_JWT_SECRETRedis/Jobs:
REDIS_URL,INNGEST_SIGNING_KEY,INNGEST_EVENT_KEYAuth:
SESSION_SECRET,SESSION_MAX_AGE,RATE_LIMIT,AUTH_PROVIDERS,isAuthProviderEnabled()Edition:
CarbonEdition(Community/Cloud/Enterprise/Test),CONTROLLED_ENVIRONMENT(ITAR flag)Maintenance and status:
MAINTENANCE_MODE(every request but/healthanswers 503),SYSTEM_STATUS_URL(optional status/announcement document)URLs:
getAppUrl(),getMESUrl(),getBrowserEnv()Logging:
LOG_LEVEL(optional, non-secret, browser-safe — consumed by@carbon/logger)Integrations: Stripe, SMTP email, Slack, Xero, Jira, OnShape, QuickBooks keys (all optional)
Web Push (
@carbon/env/push.server, server-only — importsnode:crypto):getVapidDetails(),isPushConfigured(),deriveVapidDetails(secret, appUrl). The VAPID pair is derived fromSESSION_SECRETby HKDF, so there are no push env vars; keep it out ofsrc/index.ts, which the browser imports.Feature flags (
@carbon/env/flags+@carbon/env/flags.server): spec.ai/specs/2026-10-28-feature-flags.md../flagsis browser-safe: the registryFLAGS(each flag's default and whether it goes to the browser),flagDefault,BrowserFlagKey. Add a flag there first; a key not inFLAGSis a type error. The default is the safe value: it is what an instance does with no flags source../flags.server:initFlags({ store, waitUntil, onWarning })(called once in each app'sentry.server.tsx),flags.bool(key, { companyId, email? })(never throws, default fromFLAGS; rules match the email in lower case),evaluateBrowserFlags(for the layout loaders),parseHeaders, and theFlagsStoreinterface that@carbon/kv'sredisFlagsStoreimplements (this package cannot import@carbon/kv).CARBON_FLAGS_ENDPOINT(https:polls through Redis,http:only on localhost;data:loads once; any other scheme is refused with a warning) andCARBON_FLAGS_HEADERS(OTEL headers format, secret).- Read flags only through
flags.*,evaluateBrowserFlagsanduseFeatureFlags()(@carbon/react), never with an OpenFeature client: the wrapper requirescompanyIdand takes each default fromFLAGS. Flags are booleans until one needs another type.
Cross-References
.claude/rules/environment-configuration.md— full env architecture,.envvs.env.local, URL resolutionpackages/auth/— re-exports all of@carbon/env; auth code imports from herepackages/config/— build tooling only, not runtime env (separate concern)scripts/setup-env-files.ts— symlinks root.envinto apps and packages