@maverickcer/env-cap 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +449 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/index.d.ts +3 -3
  45. package/dist/.dts/build/link.d.ts.map +1 -1
  46. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  47. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  49. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  50. package/dist/.dts/build/types.d.ts +4 -53
  51. package/dist/.dts/build/types.d.ts.map +1 -1
  52. package/dist/.dts/build/typescript.d.ts +3 -17
  53. package/dist/.dts/build/typescript.d.ts.map +1 -1
  54. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  55. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  56. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  58. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  59. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  60. package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
  61. package/dist/build-F3RQS7VE.js.map +1 -0
  62. package/dist/build.cjs +257 -102
  63. package/dist/build.cjs.map +1 -1
  64. package/dist/build.js +256 -101
  65. package/dist/build.js.map +1 -1
  66. package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
  67. package/dist/cli/index.js +36 -29
  68. package/dist/cli/index.js.map +1 -1
  69. package/dist/eslint-plugin/index.cjs +95 -54
  70. package/dist/eslint-plugin/index.cjs.map +1 -1
  71. package/dist/eslint-plugin/index.js +94 -53
  72. package/dist/eslint-plugin/index.js.map +1 -1
  73. package/examples/README.md +95 -0
  74. package/package.json +53 -19
  75. package/skills/env-cap/SKILL.md +91 -0
  76. package/skills/env-cap/references/api.md +220 -0
  77. package/specs/architecture.md +634 -0
  78. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  79. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  80. package/specs/decisions/0003-no-global-env-object.md +172 -0
  81. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  82. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  83. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  84. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  85. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  86. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  87. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  88. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  89. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  90. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  91. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  92. package/specs/decisions/0015-security-backport-window.md +60 -0
  93. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  94. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  95. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  96. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  97. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  98. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  99. package/specs/decisions/0022-validation-contexts.md +267 -0
  100. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  101. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  102. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  103. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  104. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  105. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  106. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  107. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  108. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  109. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  110. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  111. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  112. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  113. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  114. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  115. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  116. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  117. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  118. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  119. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  120. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  121. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  122. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  123. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  124. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  125. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  126. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  127. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  128. package/specs/generated-artifacts.md +104 -0
  129. package/specs/migrations/README.md +30 -0
  130. package/specs/migrations/from-centralized-schema.md +503 -0
  131. package/specs/migrations/from-dotenv.md +352 -0
  132. package/specs/migrations/from-envalid.md +482 -0
  133. package/specs/migrations/from-process-env.md +398 -0
  134. package/specs/migrations/from-t3-env.md +416 -0
  135. package/specs/migrations/from-zod.md +303 -0
  136. package/dist/build-H4KFV44Z.js.map +0 -1
  137. /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
@@ -0,0 +1,416 @@
1
+ # Migrating from t3-env
2
+
3
+ [t3-env](https://github.com/t3-oss/t3-env) is a well-designed environment validation solution built around TypeScript and Zod.
4
+
5
+ Many applications use t3-env to create a centralized, type-safe environment object:
6
+
7
+ ```ts
8
+ import { createEnv } from "@t3-oss/env-core"
9
+ import { z } from "zod"
10
+
11
+ export const env = createEnv({
12
+ server: {
13
+ DATABASE_URL: z.string().url(),
14
+ STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
15
+ },
16
+ client: {
17
+ NEXT_PUBLIC_API_URL: z.string().url(),
18
+ },
19
+ runtimeEnv: process.env,
20
+ })
21
+ ```
22
+
23
+ This provides:
24
+
25
+ - runtime validation
26
+ - type inference
27
+ - server/client variable separation
28
+ - a single validated environment object
29
+
30
+ `env-cap` does not attempt to replace t3-env's validation model.
31
+
32
+ The difference is architectural:
33
+
34
+ - `t3-env` focuses on **validating an application's environment**.
35
+ - `env-cap` focuses on **organizing configuration ownership across application capabilities**.
36
+
37
+ Both approaches solve real problems. The correct choice depends on the scale and structure of the application.
38
+
39
+ ## When t3-env works well
40
+
41
+ A centralized environment object is often the right choice when:
42
+
43
+ - one team owns the application
44
+ - configuration is relatively small
45
+ - all variables belong to the same deployment boundary
46
+ - a single application schema is easy to maintain
47
+
48
+ Example:
49
+
50
+ ```text
51
+ src/
52
+
53
+ ├── env.ts
54
+ │
55
+ ├── app/
56
+ ├── database/
57
+ └── api/
58
+ ```
59
+
60
+ In this structure, a shared environment object is simple and effective.
61
+
62
+ ## When capability ownership becomes important
63
+
64
+ As applications grow, configuration often follows business domains:
65
+
66
+ ```text
67
+ src/
68
+
69
+ ├── features/
70
+ │
71
+ ├── payments/
72
+ ├── authentication/
73
+ ├── notifications/
74
+ ├── reporting/
75
+ └── billing/
76
+ ```
77
+
78
+ Each capability has different owners, deployment concerns, and operational requirements.
79
+
80
+ A centralized environment file becomes a shared coordination point:
81
+
82
+ ```text
83
+ env.ts
84
+
85
+ ├── DATABASE_URL
86
+ ├── STRIPE_SECRET_KEY
87
+ ├── AUTH_SECRET
88
+ ├── SMTP_PASSWORD
89
+ ├── ANALYTICS_KEY
90
+ ├── REPORTING_API_URL
91
+ └── ...
92
+ ```
93
+
94
+ The problem is not validation. The problem is ownership.
95
+
96
+ Every capability change now modifies shared configuration code.
97
+
98
+ ## Migration strategy
99
+
100
+ Migrating from t3-env does not require removing Zod or rewriting validation logic.
101
+
102
+ The recommended migration is:
103
+
104
+ 1. Keep existing validation rules.
105
+ 2. Move variables into capability-owned contracts.
106
+ 3. Replace global `env` imports with capability-owned imports.
107
+ 4. Add documentation metadata where operational visibility is needed.
108
+ 5. Remove the centralized environment object after migration.
109
+
110
+ ## Before: centralized t3-env schema
111
+
112
+ Example:
113
+
114
+ ```ts
115
+ // env.ts
116
+
117
+ import { createEnv } from "@t3-oss/env-core"
118
+ import { z } from "zod"
119
+
120
+ export const env = createEnv({
121
+ server: {
122
+ STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
123
+ DATABASE_URL: z.string().url(),
124
+ },
125
+ runtimeEnv: process.env,
126
+ })
127
+ ```
128
+
129
+ Usage:
130
+
131
+ ```ts
132
+ import { env } from "@/env"
133
+
134
+ stripe.connect(env.STRIPE_SECRET_KEY)
135
+ ```
136
+
137
+ The capability depends on the application-wide environment object.
138
+
139
+ ## After: capability-owned env-cap schema
140
+
141
+ Move the configuration requirement into the owning capability:
142
+
143
+ ```ts
144
+ // features/payments/env.schema.ts
145
+
146
+ import { createEnv, documentEnv } from "@maverickcer/env-cap"
147
+ import { z } from "zod"
148
+
149
+ const paymentsSchema = {
150
+ STRIPE_SECRET_KEY: {
151
+ validator(value: string) {
152
+ return (
153
+ z.string().startsWith("sk_").safeParse(value).success ||
154
+ 'Expected a value starting with "sk_".'
155
+ )
156
+ },
157
+ },
158
+ }
159
+
160
+ export const paymentsEnv = createEnv(paymentsSchema, {
161
+ name: "payments",
162
+ })
163
+
164
+ documentEnv(paymentsSchema, {
165
+ owner: "payments-team",
166
+ variables: {
167
+ STRIPE_SECRET_KEY: {
168
+ description: "Stripe API credential used for payment processing",
169
+ },
170
+ },
171
+ })
172
+ ```
173
+
174
+ Usage:
175
+
176
+ ```ts
177
+ import { paymentsEnv } from "./env.schema"
178
+
179
+ stripe.connect(paymentsEnv.STRIPE_SECRET_KEY)
180
+ ```
181
+
182
+ The dependency is now explicit.
183
+
184
+ The payments capability depends on payments configuration, not the entire application's configuration object.
185
+
186
+ ## Reusing Zod validation
187
+
188
+ You do not need to remove Zod.
189
+
190
+ `env-cap` intentionally does not require a specific validation library.
191
+
192
+ Existing Zod schemas can be reused:
193
+
194
+ ```ts
195
+ import { z } from "zod"
196
+
197
+ const stripeKeySchema = z.string().startsWith("sk_")
198
+
199
+ const paymentsSchema = {
200
+ STRIPE_SECRET_KEY: {
201
+ validator(value: string) {
202
+ return stripeKeySchema.safeParse(value).success || 'Expected a value starting with "sk_".'
203
+ },
204
+ },
205
+ }
206
+ ```
207
+
208
+ The responsibilities become:
209
+
210
+ | Responsibility | Tool |
211
+ | ---------------------- | -------------------- |
212
+ | Environment validation | Zod |
213
+ | Capability ownership | env-cap |
214
+ | Runtime access | Capability contracts |
215
+ | Documentation metadata | `documentEnv()` |
216
+ | Project inventory | Build tooling |
217
+
218
+ ## Migrating client and server variables
219
+
220
+ t3-env provides explicit client/server separation:
221
+
222
+ ```ts
223
+ createEnv({
224
+ server: {
225
+ DATABASE_URL: z.string(),
226
+ },
227
+ client: {
228
+ NEXT_PUBLIC_API_URL: z.string(),
229
+ },
230
+ })
231
+ ```
232
+
233
+ `env-cap` handles this boundary differently.
234
+
235
+ The runtime has no separate client/server implementation because validation behavior is the same in every runtime.
236
+
237
+ Instead, separation happens through generated contract:
238
+
239
+ ```text
240
+ server.contract.ts
241
+
242
+ server-only contracts
243
+
244
+
245
+ client.contract.ts
246
+
247
+ client-safe contracts
248
+ ```
249
+
250
+ The application build decides which contracts are included.
251
+
252
+ This keeps the runtime small and avoids creating artificial package boundaries. This remains the
253
+ recommended default, and the only mechanism that actually keeps a server-only variable's source out of a
254
+ client bundle -- see [ADR 0004](../decisions/0004-no-client-server-package-split.md).
255
+
256
+ If you'd rather keep `server`/`client` variables declared in one schema location instead of splitting into
257
+ two contract files, `context`/`activeContexts` (see the README's ["Validation
258
+ contexts"](../../GUIDE.md#validation-contexts) section, [ADR 0022](../decisions/0022-validation-contexts.md))
259
+ is the closer analogue to t3-env's `server`/`client` grouping:
260
+
261
+ ```ts
262
+ createEnv({
263
+ DATABASE_URL: { context: "server", processor: (v) => String(v) },
264
+ NEXT_PUBLIC_API_URL: { context: "client", processor: (v) => String(v) },
265
+ })
266
+ ```
267
+
268
+ ```ts
269
+ // Server process:
270
+ await validateEnv({ manifest, values: process.env, activeContexts: ["server"] })
271
+ // Browser bundle:
272
+ await validateEnv({ manifest, values: window.__ENV__, activeContexts: ["client"] })
273
+ ```
274
+
275
+ This only controls whether `validateEnv()` processes a variable, not whether its definition ships to the
276
+ browser -- it's a convenience for teams that don't need a hard module boundary, not a substitute for one. If
277
+ `DATABASE_URL` must never appear in a client bundle at all, use the two-manifest approach above instead.
278
+
279
+ ## Migrating a Next.js application
280
+
281
+ A common t3-env usage:
282
+
283
+ ```ts
284
+ import { env } from "@/env"
285
+
286
+ export async function createPayment() {
287
+ return stripe(env.STRIPE_SECRET_KEY)
288
+ }
289
+ ```
290
+
291
+ Becomes:
292
+
293
+ ```ts
294
+ import { paymentsEnv } from "@/features/payments/env.schema"
295
+
296
+ export async function createPayment() {
297
+ return stripe(paymentsEnv.STRIPE_SECRET_KEY)
298
+ }
299
+ ```
300
+
301
+ The capability now declares its own configuration dependency.
302
+
303
+ ## Handling shared variables
304
+
305
+ A centralized environment object assumes one global interpretation:
306
+
307
+ ```ts
308
+ env.SOME_VARIABLE
309
+ ```
310
+
311
+ However, different capabilities may require different transformations.
312
+
313
+ Example:
314
+
315
+ ```env
316
+ CACHE_TIMEOUT=60000
317
+ ```
318
+
319
+ A caching capability may require:
320
+
321
+ ```ts
322
+ cacheEnv.CACHE_TIMEOUT
323
+ // number
324
+ ```
325
+
326
+ because it performs calculations.
327
+
328
+ A monitoring capability may require:
329
+
330
+ ```ts
331
+ monitoringEnv.CACHE_TIMEOUT
332
+ // string
333
+ ```
334
+
335
+ because it reports configuration values.
336
+
337
+ A single global object cannot represent both interpretations without choosing one as the default.
338
+
339
+ Capability-owned contracts allow each capability to define the meaning it requires.
340
+
341
+ ## Generating project-wide visibility
342
+
343
+ One advantage of centralized systems is visibility:
344
+
345
+ ```ts
346
+ env.DATABASE_URL
347
+ env.STRIPE_SECRET_KEY
348
+ env.REDIS_URL
349
+ ```
350
+
351
+ Developers can quickly see available configuration.
352
+
353
+ `env-cap` provides the same visibility through build artifacts instead of runtime structure.
354
+
355
+ The build system can generate:
356
+
357
+ - environment contract
358
+ - documentation
359
+ - `.env.example` files
360
+ - configuration reports
361
+
362
+ The runtime remains modular while platform teams still have a complete inventory.
363
+
364
+ ## When to keep t3-env
365
+
366
+ t3-env may remain the better choice when:
367
+
368
+ - your application has one configuration owner
369
+ - the centralized schema is easy to maintain
370
+ - capability boundaries are not important
371
+ - documentation and lifecycle tracking are handled elsewhere
372
+
373
+ `t3-env` is an excellent validation solution.
374
+
375
+ `env-cap` is designed for applications where configuration ownership becomes an architectural concern.
376
+
377
+ ## Summary
378
+
379
+ Migrating from t3-env changes the organization model, not the validation strategy.
380
+
381
+ Before:
382
+
383
+ ```text
384
+ application
385
+
386
+ env.ts
387
+
388
+ DATABASE_URL
389
+ STRIPE_SECRET_KEY
390
+ AUTH_SECRET
391
+ ```
392
+
393
+ After:
394
+
395
+ ```text
396
+ application
397
+
398
+ database
399
+ env.schema.ts
400
+
401
+ payments
402
+ env.schema.ts
403
+
404
+ authentication
405
+ env.schema.ts
406
+ ```
407
+
408
+ `t3-env` answers:
409
+
410
+ > "Are these environment variables valid?"
411
+
412
+ `env-cap` answers:
413
+
414
+ > "Who owns these environment variables, where are they used, and how do we operate them as the system grows?"
415
+
416
+ The two approaches can also coexist. Existing validation logic can remain while configuration ownership gradually moves closer to the capabilities that depend on it.
@@ -0,0 +1,303 @@
1
+ # Migrating from Zod environment validation
2
+
3
+ Zod is an excellent schema validation library. Many applications use Zod to create a single validated environment object:
4
+
5
+ ```ts
6
+ // env.ts
7
+
8
+ import { z } from "zod"
9
+
10
+ const envSchema = z.object({
11
+ DATABASE_URL: z.string().url(),
12
+ STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
13
+ PORT: z.coerce.number().default(3000),
14
+ })
15
+
16
+ export const env = envSchema.parse(process.env)
17
+ ```
18
+
19
+ This approach provides:
20
+
21
+ - runtime validation
22
+ - type inference
23
+ - clear validation rules
24
+ - a single access point for configuration
25
+
26
+ `env-cap` does not replace Zod. It addresses a different architectural concern: configuration ownership.
27
+
28
+ A centralized environment object works well when the entire application has one configuration owner. As applications grow, especially across teams or domains, the environment schema often becomes a shared dependency that every capability must modify.
29
+
30
+ `env-cap` moves configuration ownership to the capability that consumes it while allowing teams to continue using their preferred validation approach.
31
+
32
+ ## Migration goals
33
+
34
+ A migration from Zod does not require rewriting every validation rule.
35
+
36
+ The recommended approach is incremental:
37
+
38
+ 1. Identify which capability owns each environment variable.
39
+ 2. Move variables from the centralized schema into capability-owned schemas.
40
+ 3. Keep existing validation logic where possible.
41
+ 4. Replace global environment access with capability-owned contracts.
42
+ 5. Generate project-wide documentation and visibility through build tooling.
43
+
44
+ ## Before: centralized environment schema
45
+
46
+ A common pattern:
47
+
48
+ ```ts
49
+ // env.ts
50
+
51
+ import { z } from "zod"
52
+
53
+ export const env = z
54
+ .object({
55
+ DATABASE_URL: z.string().url(),
56
+ STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
57
+ REDIS_URL: z.string(),
58
+ })
59
+ .parse(process.env)
60
+ ```
61
+
62
+ Usage:
63
+
64
+ ```ts
65
+ import { env } from "./env"
66
+
67
+ await connectDatabase(env.DATABASE_URL)
68
+ await stripe.connect(env.STRIPE_SECRET_KEY)
69
+ ```
70
+
71
+ The challenge is not validation. The challenge is ownership.
72
+
73
+ As capabilities grow:
74
+
75
+ ```text
76
+ env.ts
77
+
78
+ ├── database variables
79
+ ├── payments variables
80
+ ├── authentication variables
81
+ ├── notifications variables
82
+ ├── analytics variables
83
+ └── internal tooling variables
84
+ ```
85
+
86
+ Every capability now depends on the same configuration file.
87
+
88
+ ## After: capability-owned contracts
89
+
90
+ Move configuration next to the capability that owns it.
91
+
92
+ Example:
93
+
94
+ ```ts
95
+ // features/payments/env.schema.ts
96
+
97
+ import { createEnv, documentEnv } from "@maverickcer/env-cap"
98
+ import { z } from "zod"
99
+
100
+ const paymentsSchema = {
101
+ STRIPE_SECRET_KEY: {
102
+ validator(value: string) {
103
+ return (
104
+ z.string().startsWith("sk_").safeParse(value).success ||
105
+ 'Expected a value starting with "sk_".'
106
+ )
107
+ },
108
+ },
109
+ }
110
+
111
+ export const paymentsEnv = createEnv(paymentsSchema, {
112
+ name: "payments",
113
+ })
114
+
115
+ documentEnv(paymentsSchema, {
116
+ owner: "payments-team",
117
+ variables: {
118
+ STRIPE_SECRET_KEY: {
119
+ description: "Stripe API credential used for payment processing",
120
+ },
121
+ },
122
+ })
123
+ ```
124
+
125
+ Usage:
126
+
127
+ ```ts
128
+ import { paymentsEnv } from "./env.schema"
129
+
130
+ stripe.connect(paymentsEnv.STRIPE_SECRET_KEY)
131
+ ```
132
+
133
+ The validation rule remains owned by the payments capability.
134
+
135
+ ## Keeping Zod validators
136
+
137
+ `env-cap` intentionally does not require a specific validation library.
138
+
139
+ Existing Zod schemas can be reused:
140
+
141
+ ```ts
142
+ import { z } from "zod"
143
+
144
+ const portSchema = z.coerce.number().int().positive()
145
+
146
+ const serverSchema = {
147
+ PORT: {
148
+ processor(value: string) {
149
+ return portSchema.parse(value)
150
+ },
151
+ validator(value: number) {
152
+ return value > 0 || "Expected a positive integer."
153
+ },
154
+ },
155
+ }
156
+ ```
157
+
158
+ The responsibilities become:
159
+
160
+ | Responsibility | Tool |
161
+ | ----------------------- | -------------------------- |
162
+ | Schema validation | Zod |
163
+ | Value processing | Zod or custom processors |
164
+ | Capability ownership | env-cap |
165
+ | Runtime access | Capability-owned contracts |
166
+ | Documentation | documentEnv |
167
+ | Configuration inventory | Build tooling |
168
+
169
+ ## Handling the generated global environment object
170
+
171
+ Many Zod implementations expose:
172
+
173
+ ```ts
174
+ env.DATABASE_URL
175
+ env.STRIPE_SECRET_KEY
176
+ ```
177
+
178
+ During migration, replace this with imports from the owning capability:
179
+
180
+ ```ts
181
+ // Before
182
+
183
+ import { env } from "@/env"
184
+
185
+ env.STRIPE_SECRET_KEY
186
+ ```
187
+
188
+ ```ts
189
+ // After
190
+
191
+ import { paymentsEnv } from "@/features/payments/env.schema"
192
+
193
+ paymentsEnv.STRIPE_SECRET_KEY
194
+ ```
195
+
196
+ This makes dependencies explicit.
197
+
198
+ A payments module that requires Stripe credentials should import the payments configuration instead of depending on an application-wide environment object.
199
+
200
+ ## Migrating gradually
201
+
202
+ A full migration does not need to happen at once.
203
+
204
+ A practical sequence:
205
+
206
+ ### Step 1: Keep the existing Zod schema
207
+
208
+ Continue validating existing variables.
209
+
210
+ ### Step 2: Split variables by ownership
211
+
212
+ Move one capability at a time:
213
+
214
+ ```text
215
+ features/
216
+ ├── payments/
217
+ │ └── env.schema.ts
218
+ ├── database/
219
+ │ └── env.schema.ts
220
+ └── authentication/
221
+ └── env.schema.ts
222
+ ```
223
+
224
+ ### Step 3: Replace imports
225
+
226
+ Move consumers from:
227
+
228
+ ```ts
229
+ env.SOME_VARIABLE
230
+ ```
231
+
232
+ to:
233
+
234
+ ```ts
235
+ capabilityEnv.SOME_VARIABLE
236
+ ```
237
+
238
+ ### Step 4: Add documentation metadata
239
+
240
+ Once ownership is clear:
241
+
242
+ ```ts
243
+ documentEnv(schema, {
244
+ owner: "team-name",
245
+ variables: {
246
+ SOME_VARIABLE: {
247
+ description: "Purpose of this configuration value",
248
+ },
249
+ },
250
+ })
251
+ ```
252
+
253
+ ### Step 5: Remove the centralized schema
254
+
255
+ After all consumers migrate, the original global environment object can be removed.
256
+
257
+ ## When to keep Zod alone
258
+
259
+ `env-cap` may not provide significant value if:
260
+
261
+ - the application is small
262
+ - one team owns all configuration
263
+ - environment variables are few and stable
264
+ - a centralized schema is not creating friction
265
+
266
+ Zod remains an excellent choice for these applications.
267
+
268
+ `env-cap` is designed for applications where configuration ownership becomes difficult to manage as the system grows.
269
+
270
+ ## Summary
271
+
272
+ Migrating from Zod does not mean replacing Zod.
273
+
274
+ The migration changes the ownership model:
275
+
276
+ Before:
277
+
278
+ ```text
279
+ application
280
+ |
281
+ └── env.ts
282
+ |
283
+ ├── DATABASE_URL
284
+ ├── STRIPE_SECRET_KEY
285
+ └── REDIS_URL
286
+ ```
287
+
288
+ After:
289
+
290
+ ```text
291
+ application
292
+
293
+ database
294
+ └── env.schema.ts
295
+
296
+ payments
297
+ └── env.schema.ts
298
+
299
+ cache
300
+ └── env.schema.ts
301
+ ```
302
+
303
+ Validation remains where it belongs. Configuration ownership becomes modular. Build tooling provides the global visibility needed by platform teams without making the runtime depend on a global configuration object.