@maverickcer/env-cap 0.7.7 → 0.8.0
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.
- package/ADOPTION.md +4 -4
- package/AGENTS.md +2 -3
- package/CHANGELOG.md +27 -0
- package/CODE_REVIEW.md +1 -1
- package/CONTRIBUTING.md +1 -1
- package/GUIDE.md +12 -12
- package/README.md +11 -12
- package/VERSIONING.md +2 -1
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +3 -4
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/assemble-project.d.ts +3 -3
- package/dist/.dts/build/change-model.d.ts +9 -11
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts +5 -6
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts +6 -7
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/contract-model.d.ts +7 -8
- package/dist/.dts/build/contract-model.d.ts.map +1 -1
- package/dist/.dts/build/deep-equal.d.ts +3 -3
- package/dist/.dts/build/deep-freeze.d.ts +5 -7
- package/dist/.dts/build/deep-freeze.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts +2 -2
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.d.ts +6 -6
- package/dist/.dts/build/discover.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts +6 -7
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/errors.d.ts +4 -4
- package/dist/.dts/build/evidence-cache.d.ts +12 -14
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +6 -7
- package/dist/.dts/build/evidence-model.d.ts.map +1 -1
- package/dist/.dts/build/evidence-reference.d.ts +6 -6
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts/build/exclusive-group.d.ts +3 -3
- package/dist/.dts/build/finding-model.d.ts +12 -13
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts +6 -7
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts +13 -15
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +14 -16
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +3 -3
- package/dist/.dts/build/governance-fields.d.ts +3 -3
- package/dist/.dts/build/humanize-key.d.ts +3 -3
- package/dist/.dts/build/lifecycle-model.d.ts +3 -3
- package/dist/.dts/build/literal-eval.d.ts +2 -2
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts +9 -9
- package/dist/.dts/build/manifest.d.ts +7 -8
- package/dist/.dts/build/manifest.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +4 -5
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +8 -9
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +4 -4
- package/dist/.dts/build/sarif.d.ts +9 -11
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/source-position.d.ts +14 -17
- package/dist/.dts/build/source-position.d.ts.map +1 -1
- package/dist/.dts/build/usage-report.d.ts +16 -17
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/cli/filesystem.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +2 -2
- package/dist/.dts/eslint-plugin/index.d.ts +2 -1
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +5 -5
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts/evidence/define-projection.d.ts +6 -6
- package/dist/.dts/runtime/create.d.ts +2 -3
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/errors.d.ts +7 -8
- package/dist/.dts/runtime/errors.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +2 -2
- package/dist/.dts/runtime/types.d.ts +18 -20
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +2 -2
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +3 -4
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts7/build/assemble-project.d.ts +3 -3
- package/dist/.dts7/build/change-model.d.ts +9 -11
- package/dist/.dts7/build/change-model.d.ts.map +1 -1
- package/dist/.dts7/build/check-artifacts.d.ts +5 -6
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts7/build/citation-verification.d.ts +6 -7
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts7/build/contract-model.d.ts +7 -8
- package/dist/.dts7/build/contract-model.d.ts.map +1 -1
- package/dist/.dts7/build/deep-equal.d.ts +3 -3
- package/dist/.dts7/build/deep-freeze.d.ts +5 -7
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -1
- package/dist/.dts7/build/dependency-model.d.ts +2 -2
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts7/build/discover.d.ts +6 -6
- package/dist/.dts7/build/discover.d.ts.map +1 -1
- package/dist/.dts7/build/env-example.d.ts +6 -7
- package/dist/.dts7/build/env-example.d.ts.map +1 -1
- package/dist/.dts7/build/errors.d.ts +4 -4
- package/dist/.dts7/build/evidence-cache.d.ts +12 -14
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts7/build/evidence-model.d.ts +6 -7
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -1
- package/dist/.dts7/build/evidence-reference.d.ts +6 -6
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts7/build/exclusive-group.d.ts +3 -3
- package/dist/.dts7/build/finding-model.d.ts +12 -13
- package/dist/.dts7/build/finding-model.d.ts.map +1 -1
- package/dist/.dts7/build/generate-documentation.d.ts +6 -7
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts7/build/generate-evidence.d.ts +13 -15
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts7/build/generate-manifest.d.ts +14 -16
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts7/build/generated-banner.d.ts +3 -3
- package/dist/.dts7/build/governance-fields.d.ts +3 -3
- package/dist/.dts7/build/humanize-key.d.ts +3 -3
- package/dist/.dts7/build/lifecycle-model.d.ts +3 -3
- package/dist/.dts7/build/literal-eval.d.ts +2 -2
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts7/build/live-expirations.d.ts +9 -9
- package/dist/.dts7/build/manifest.d.ts +7 -8
- package/dist/.dts7/build/manifest.d.ts.map +1 -1
- package/dist/.dts7/build/merge-documentation.d.ts +4 -5
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts7/build/resolution/resolve-import.d.ts +8 -9
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +4 -4
- package/dist/.dts7/build/sarif.d.ts +9 -11
- package/dist/.dts7/build/sarif.d.ts.map +1 -1
- package/dist/.dts7/build/source-position.d.ts +14 -17
- package/dist/.dts7/build/source-position.d.ts.map +1 -1
- package/dist/.dts7/build/usage-report.d.ts +16 -17
- package/dist/.dts7/build/usage-report.d.ts.map +1 -1
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -1
- package/dist/.dts7/eslint-plugin/glob.d.ts +2 -2
- package/dist/.dts7/eslint-plugin/index.d.ts +2 -1
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +5 -5
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts7/evidence/define-projection.d.ts +6 -6
- package/dist/.dts7/runtime/create.d.ts +2 -3
- package/dist/.dts7/runtime/create.d.ts.map +1 -1
- package/dist/.dts7/runtime/errors.d.ts +7 -8
- package/dist/.dts7/runtime/errors.d.ts.map +1 -1
- package/dist/.dts7/runtime/index.d.ts +2 -2
- package/dist/.dts7/runtime/types.d.ts +18 -20
- package/dist/.dts7/runtime/types.d.ts.map +1 -1
- package/dist/.dts7/runtime/validate.d.ts +2 -2
- package/dist/.dts7/runtime/validate.d.ts.map +1 -1
- package/dist/{build-33O5SDTC.js → build-Z76NCC65.js} +7 -10
- package/dist/build-Z76NCC65.js.map +1 -0
- package/dist/build.cjs +6 -9
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +6 -9
- package/dist/build.js.map +1 -1
- package/dist/{chunk-4D67AQFY.js → chunk-JRCMG4FQ.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/node.cjs.map +1 -1
- package/dist/node.js.map +1 -1
- package/package.json +6 -4
- package/schemas/env-cap-report.schema.json +11 -11
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +6 -6
- package/specs/migrations/README.md +9 -9
- package/specs/migrations/from-centralized-schema.md +28 -28
- package/specs/migrations/from-dotenv.md +11 -11
- package/specs/migrations/from-envalid.md +16 -16
- package/specs/migrations/from-process-env.md +19 -19
- package/specs/migrations/from-t3-env.md +24 -24
- package/specs/migrations/from-zod.md +21 -21
- package/dist/build-33O5SDTC.js.map +0 -1
- /package/dist/{chunk-4D67AQFY.js.map → chunk-JRCMG4FQ.js.map} +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Migrating from a Centralized Environment Schema
|
|
2
2
|
|
|
3
|
-
This guide explains how to migrate from a centralized environment configuration model into
|
|
3
|
+
This guide explains how to migrate from a centralized environment configuration model into feature-owned environment contracts.
|
|
4
4
|
|
|
5
5
|
Examples of centralized schemas include:
|
|
6
6
|
|
|
@@ -26,15 +26,15 @@ Centralized schemas are a reasonable starting point. They provide a clear locati
|
|
|
26
26
|
|
|
27
27
|
As applications grow, however, the centralized file becomes a shared ownership boundary:
|
|
28
28
|
|
|
29
|
-
- Every
|
|
29
|
+
- Every feature change modifies the same file.
|
|
30
30
|
- Teams become dependent on whoever owns the schema.
|
|
31
|
-
- Removing
|
|
32
|
-
- Configuration ownership becomes separated from
|
|
31
|
+
- Removing features requires finding unused configuration manually.
|
|
32
|
+
- Configuration ownership becomes separated from feature ownership.
|
|
33
33
|
- Merge conflicts increase as the application grows.
|
|
34
34
|
|
|
35
35
|
`env-cap` does not replace your validation system. It changes where environment ownership lives.
|
|
36
36
|
|
|
37
|
-
You can continue using Zod, Valibot, Joi, custom validators, or simple functions inside
|
|
37
|
+
You can continue using Zod, Valibot, Joi, custom validators, or simple functions inside feature contracts.
|
|
38
38
|
|
|
39
39
|
The migration goal is:
|
|
40
40
|
|
|
@@ -42,7 +42,7 @@ The migration goal is:
|
|
|
42
42
|
centralized configuration
|
|
43
43
|
|
|
|
44
44
|
v
|
|
45
|
-
|
|
45
|
+
feature-owned contracts
|
|
46
46
|
|
|
|
47
47
|
v
|
|
48
48
|
generated project-wide visibility
|
|
@@ -78,7 +78,7 @@ export const env = createConfig({
|
|
|
78
78
|
})
|
|
79
79
|
```
|
|
80
80
|
|
|
81
|
-
Every
|
|
81
|
+
Every feature imports the same object:
|
|
82
82
|
|
|
83
83
|
```ts
|
|
84
84
|
import { env } from "./env"
|
|
@@ -94,13 +94,13 @@ The problem is not the validation.
|
|
|
94
94
|
|
|
95
95
|
The problem is ownership.
|
|
96
96
|
|
|
97
|
-
The database
|
|
97
|
+
The database feature owns `DATABASE_URL`, but the database configuration lives somewhere else.
|
|
98
98
|
|
|
99
99
|
---
|
|
100
100
|
|
|
101
101
|
## Migration strategy
|
|
102
102
|
|
|
103
|
-
Migrate one
|
|
103
|
+
Migrate one feature at a time.
|
|
104
104
|
|
|
105
105
|
Do not move every variable into `env-cap` immediately.
|
|
106
106
|
|
|
@@ -134,7 +134,7 @@ The application can temporarily support both approaches.
|
|
|
134
134
|
|
|
135
135
|
## Step 1: Identify ownership
|
|
136
136
|
|
|
137
|
-
For each variable, determine which
|
|
137
|
+
For each variable, determine which feature requires it.
|
|
138
138
|
|
|
139
139
|
Example centralized schema:
|
|
140
140
|
|
|
@@ -160,13 +160,13 @@ Ownership should follow usage, not technical category.
|
|
|
160
160
|
|
|
161
161
|
A variable is not "database configuration" because it contains `DATABASE`.
|
|
162
162
|
|
|
163
|
-
It belongs to the
|
|
163
|
+
It belongs to the feature that defines how it is consumed.
|
|
164
164
|
|
|
165
165
|
---
|
|
166
166
|
|
|
167
|
-
## Step 2: Create
|
|
167
|
+
## Step 2: Create feature schemas
|
|
168
168
|
|
|
169
|
-
Create a schema next to the
|
|
169
|
+
Create a schema next to the feature.
|
|
170
170
|
|
|
171
171
|
Example:
|
|
172
172
|
|
|
@@ -199,7 +199,7 @@ documentEnv(paymentsSchema, {
|
|
|
199
199
|
})
|
|
200
200
|
```
|
|
201
201
|
|
|
202
|
-
The
|
|
202
|
+
The feature now owns its configuration.
|
|
203
203
|
|
|
204
204
|
---
|
|
205
205
|
|
|
@@ -233,7 +233,7 @@ paymentsEnv
|
|
|
233
233
|
payments schema
|
|
234
234
|
```
|
|
235
235
|
|
|
236
|
-
The
|
|
236
|
+
The feature no longer depends on a global configuration object.
|
|
237
237
|
|
|
238
238
|
---
|
|
239
239
|
|
|
@@ -302,7 +302,7 @@ await generateEnvManifest({
|
|
|
302
302
|
This allows tooling to answer:
|
|
303
303
|
|
|
304
304
|
- Which variables exist?
|
|
305
|
-
- Which
|
|
305
|
+
- Which feature owns them?
|
|
306
306
|
- Which variables are undocumented?
|
|
307
307
|
- Which variables are expiring?
|
|
308
308
|
- Which variables have possible conflicts?
|
|
@@ -317,11 +317,11 @@ The platform view remains centralized.
|
|
|
317
317
|
|
|
318
318
|
A common migration concern is:
|
|
319
319
|
|
|
320
|
-
> "What happens if multiple
|
|
320
|
+
> "What happens if multiple features use the same environment variable?"
|
|
321
321
|
|
|
322
322
|
The answer depends on whether the value has the same meaning.
|
|
323
323
|
|
|
324
|
-
If multiple
|
|
324
|
+
If multiple features consume the same value with identical requirements, create a shared ownership module:
|
|
325
325
|
|
|
326
326
|
```text
|
|
327
327
|
features/
|
|
@@ -329,7 +329,7 @@ features/
|
|
|
329
329
|
└── env.schema.ts
|
|
330
330
|
```
|
|
331
331
|
|
|
332
|
-
Other
|
|
332
|
+
Other features import the database contract:
|
|
333
333
|
|
|
334
334
|
```ts
|
|
335
335
|
import { databaseEnv } from "../database/env.schema"
|
|
@@ -337,15 +337,15 @@ import { databaseEnv } from "../database/env.schema"
|
|
|
337
337
|
databaseEnv.DATABASE_URL
|
|
338
338
|
```
|
|
339
339
|
|
|
340
|
-
If different
|
|
340
|
+
If different features interpret the same raw value differently, keep those interpretations local.
|
|
341
341
|
|
|
342
342
|
Example:
|
|
343
343
|
|
|
344
344
|
```ts
|
|
345
|
-
// metrics
|
|
345
|
+
// metrics feature
|
|
346
346
|
REPORT_INTERVAL_MS -> number
|
|
347
347
|
|
|
348
|
-
// logging
|
|
348
|
+
// logging feature
|
|
349
349
|
REPORT_INTERVAL_MS -> string identifier
|
|
350
350
|
```
|
|
351
351
|
|
|
@@ -353,7 +353,7 @@ Both consume the same underlying environment value, but their application requir
|
|
|
353
353
|
|
|
354
354
|
A centralized schema must choose one global representation.
|
|
355
355
|
|
|
356
|
-
|
|
356
|
+
Feature contracts allow each consumer to define its own validated view.
|
|
357
357
|
|
|
358
358
|
---
|
|
359
359
|
|
|
@@ -411,7 +411,7 @@ features/
|
|
|
411
411
|
└── env.schema.ts
|
|
412
412
|
```
|
|
413
413
|
|
|
414
|
-
Configuration should follow
|
|
414
|
+
Configuration should follow feature ownership.
|
|
415
415
|
|
|
416
416
|
---
|
|
417
417
|
|
|
@@ -432,7 +432,7 @@ This recreates the same coupling:
|
|
|
432
432
|
env.payments.STRIPE_SECRET_KEY
|
|
433
433
|
```
|
|
434
434
|
|
|
435
|
-
The
|
|
435
|
+
The feature import itself should define the dependency.
|
|
436
436
|
|
|
437
437
|
---
|
|
438
438
|
|
|
@@ -481,9 +481,9 @@ After migration:
|
|
|
481
481
|
|
|
482
482
|
| Responsibility | Location |
|
|
483
483
|
| ------------------ | ------------------- |
|
|
484
|
-
| Variable ownership |
|
|
485
|
-
| Validation logic |
|
|
486
|
-
| Runtime access |
|
|
484
|
+
| Variable ownership | Feature schema |
|
|
485
|
+
| Validation logic | Feature schema |
|
|
486
|
+
| Runtime access | Feature contract |
|
|
487
487
|
| Documentation | `documentEnv()` |
|
|
488
488
|
| Project visibility | Generated artifacts |
|
|
489
489
|
| Platform reporting | Build tooling |
|
|
@@ -43,7 +43,7 @@ You can continue using:
|
|
|
43
43
|
The migration path is:
|
|
44
44
|
|
|
45
45
|
1. Keep `dotenv` responsible for loading values.
|
|
46
|
-
2. Create
|
|
46
|
+
2. Create feature-owned environment schemas.
|
|
47
47
|
3. Replace direct `process.env` access with validated contracts.
|
|
48
48
|
4. Add documentation metadata when needed.
|
|
49
49
|
5. Generate configuration artifacts through build tooling.
|
|
@@ -84,11 +84,11 @@ This creates several problems:
|
|
|
84
84
|
- validation logic is duplicated
|
|
85
85
|
- ownership is unclear
|
|
86
86
|
- variables can disappear from documentation
|
|
87
|
-
- unused variables remain after
|
|
87
|
+
- unused variables remain after features are removed
|
|
88
88
|
|
|
89
|
-
## After:
|
|
89
|
+
## After: feature-owned environment contracts
|
|
90
90
|
|
|
91
|
-
Move configuration requirements alongside the
|
|
91
|
+
Move configuration requirements alongside the feature that uses them.
|
|
92
92
|
|
|
93
93
|
Example:
|
|
94
94
|
|
|
@@ -119,7 +119,7 @@ documentEnv(paymentsSchema, {
|
|
|
119
119
|
})
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
-
The
|
|
122
|
+
The feature now owns its configuration:
|
|
123
123
|
|
|
124
124
|
```ts
|
|
125
125
|
import { paymentsEnv } from "./env.schema"
|
|
@@ -146,7 +146,7 @@ process.env
|
|
|
146
146
|
env-cap validation
|
|
147
147
|
|
|
|
148
148
|
v
|
|
149
|
-
|
|
149
|
+
feature-owned environment contract
|
|
150
150
|
```
|
|
151
151
|
|
|
152
152
|
Example startup:
|
|
@@ -182,7 +182,7 @@ Search for:
|
|
|
182
182
|
process.env
|
|
183
183
|
```
|
|
184
184
|
|
|
185
|
-
Identify which
|
|
185
|
+
Identify which feature owns each variable.
|
|
186
186
|
|
|
187
187
|
Example:
|
|
188
188
|
|
|
@@ -198,9 +198,9 @@ features/payments/
|
|
|
198
198
|
|
|
199
199
|
not a global configuration file.
|
|
200
200
|
|
|
201
|
-
### Step 2: Create
|
|
201
|
+
### Step 2: Create feature schemas
|
|
202
202
|
|
|
203
|
-
Move variables into
|
|
203
|
+
Move variables into feature-owned schemas:
|
|
204
204
|
|
|
205
205
|
```text
|
|
206
206
|
features/
|
|
@@ -229,7 +229,7 @@ After:
|
|
|
229
229
|
const key = paymentsEnv.STRIPE_SECRET_KEY
|
|
230
230
|
```
|
|
231
231
|
|
|
232
|
-
The
|
|
232
|
+
The feature now receives a validated value instead of an unknown string.
|
|
233
233
|
|
|
234
234
|
### Step 4: Add documentation metadata
|
|
235
235
|
|
|
@@ -341,7 +341,7 @@ dotenv
|
|
|
341
341
|
process.env
|
|
342
342
|
|
|
|
343
343
|
v
|
|
344
|
-
|
|
344
|
+
feature-owned env contracts
|
|
345
345
|
|
|
|
346
346
|
v
|
|
347
347
|
validated application code
|
|
@@ -13,7 +13,7 @@ The migration is not a replacement of validation capabilities. `envalid` and
|
|
|
13
13
|
|
|
14
14
|
`env-cap` can use the same validation approach you already have today,
|
|
15
15
|
including custom validators and processors. The primary change is moving
|
|
16
|
-
from a centralized configuration object to
|
|
16
|
+
from a centralized configuration object to feature-owned environment
|
|
17
17
|
contracts.
|
|
18
18
|
|
|
19
19
|
## Before: centralized environment validation
|
|
@@ -50,18 +50,18 @@ src/
|
|
|
50
50
|
└── notifications/
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
Every
|
|
53
|
+
Every feature that requires configuration modifies the same file.
|
|
54
54
|
|
|
55
55
|
Common consequences:
|
|
56
56
|
|
|
57
57
|
- configuration ownership becomes unclear
|
|
58
|
-
- unrelated
|
|
59
|
-
- removing
|
|
58
|
+
- unrelated features modify the same schema
|
|
59
|
+
- removing features requires cleaning up centralized variables
|
|
60
60
|
- platform teams need separate tooling to understand ownership
|
|
61
61
|
|
|
62
|
-
## After:
|
|
62
|
+
## After: feature-owned contracts
|
|
63
63
|
|
|
64
|
-
With `env-cap`, move configuration ownership into the
|
|
64
|
+
With `env-cap`, move configuration ownership into the feature that uses
|
|
65
65
|
it.
|
|
66
66
|
|
|
67
67
|
Example:
|
|
@@ -76,7 +76,7 @@ src/
|
|
|
76
76
|
└── env.schema.ts
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
The database
|
|
79
|
+
The database feature owns database configuration:
|
|
80
80
|
|
|
81
81
|
```ts
|
|
82
82
|
// database/env.schema.ts
|
|
@@ -96,7 +96,7 @@ export const databaseEnv = createEnv(databaseSchema, {
|
|
|
96
96
|
})
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
The payments
|
|
99
|
+
The payments feature owns payment configuration:
|
|
100
100
|
|
|
101
101
|
```ts
|
|
102
102
|
// payments/env.schema.ts
|
|
@@ -116,7 +116,7 @@ export const paymentsEnv = createEnv(paymentsSchema, {
|
|
|
116
116
|
})
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
-
Application code imports configuration from the
|
|
119
|
+
Application code imports configuration from the feature that owns it:
|
|
120
120
|
|
|
121
121
|
```ts
|
|
122
122
|
import { databaseEnv } from "./database/env.schema"
|
|
@@ -161,7 +161,7 @@ The package only validates and exposes configuration.
|
|
|
161
161
|
|
|
162
162
|
---
|
|
163
163
|
|
|
164
|
-
### Step 2: Identify
|
|
164
|
+
### Step 2: Identify feature ownership
|
|
165
165
|
|
|
166
166
|
Start by grouping existing variables by the code that consumes them.
|
|
167
167
|
|
|
@@ -252,7 +252,7 @@ PORT: {
|
|
|
252
252
|
|
|
253
253
|
The important distinction is that transformation and validation are explicit.
|
|
254
254
|
|
|
255
|
-
The runtime contract defines how the
|
|
255
|
+
The runtime contract defines how the feature consumes the value.
|
|
256
256
|
|
|
257
257
|
---
|
|
258
258
|
|
|
@@ -326,7 +326,7 @@ export function createPayment() {
|
|
|
326
326
|
}
|
|
327
327
|
```
|
|
328
328
|
|
|
329
|
-
Continue migrating
|
|
329
|
+
Continue migrating feature by feature until the centralized environment object
|
|
330
330
|
is no longer needed.
|
|
331
331
|
|
|
332
332
|
---
|
|
@@ -351,7 +351,7 @@ The difference is the ownership model.
|
|
|
351
351
|
|
|
352
352
|
`env-cap` answers:
|
|
353
353
|
|
|
354
|
-
> "Which
|
|
354
|
+
> "Which feature owns this configuration, how is it validated, and how is it
|
|
355
355
|
> operated over time?"
|
|
356
356
|
|
|
357
357
|
---
|
|
@@ -388,7 +388,7 @@ timeout: "5000"
|
|
|
388
388
|
A library integration may require a string because it serializes directly into
|
|
389
389
|
headers or configuration.
|
|
390
390
|
|
|
391
|
-
Another
|
|
391
|
+
Another feature may require:
|
|
392
392
|
|
|
393
393
|
```ts
|
|
394
394
|
timeout: 5000
|
|
@@ -402,7 +402,7 @@ timeout + retryDelay
|
|
|
402
402
|
|
|
403
403
|
The environment value is the same. The consumer requirement is different.
|
|
404
404
|
|
|
405
|
-
`env-cap` allows each owning
|
|
405
|
+
`env-cap` allows each owning feature to define its own processing boundary:
|
|
406
406
|
|
|
407
407
|
```ts
|
|
408
408
|
apiClientEnv.TIMEOUT
|
|
@@ -471,7 +471,7 @@ These tools solve environment parsing and validation.
|
|
|
471
471
|
|
|
472
472
|
`env-cap` adds the organizational layer:
|
|
473
473
|
|
|
474
|
-
-
|
|
474
|
+
- feature ownership
|
|
475
475
|
- static discovery
|
|
476
476
|
- generated documentation
|
|
477
477
|
- lifecycle visibility
|
|
@@ -10,7 +10,7 @@ const stripeKey = process.env.STRIPE_SECRET_KEY
|
|
|
10
10
|
This approach is flexible and requires no additional tooling. However, as applications grow, direct `process.env` access creates several challenges:
|
|
11
11
|
|
|
12
12
|
- Environment requirements are scattered throughout the codebase.
|
|
13
|
-
- Validation logic is repeated across
|
|
13
|
+
- Validation logic is repeated across features.
|
|
14
14
|
- It is difficult to identify which part of the application owns a variable.
|
|
15
15
|
- Removing unused configuration requires manually searching for references.
|
|
16
16
|
- Platform teams lack a reliable inventory of application configuration.
|
|
@@ -26,7 +26,7 @@ process.env
|
|
|
26
26
|
env-cap validation
|
|
27
27
|
|
|
|
28
28
|
v
|
|
29
|
-
|
|
29
|
+
feature-owned environment contract
|
|
30
30
|
|
|
|
31
31
|
v
|
|
32
32
|
application code
|
|
@@ -37,8 +37,8 @@ application code
|
|
|
37
37
|
The recommended migration path is incremental:
|
|
38
38
|
|
|
39
39
|
1. Find existing environment variable usage.
|
|
40
|
-
2. Group variables by the
|
|
41
|
-
3. Create
|
|
40
|
+
2. Group variables by the feature that consumes them.
|
|
41
|
+
3. Create feature-owned environment contracts.
|
|
42
42
|
4. Replace direct `process.env` reads with validated access.
|
|
43
43
|
5. Generate project-wide configuration artifacts through build tooling.
|
|
44
44
|
|
|
@@ -86,9 +86,9 @@ process.env
|
|
|
86
86
|
|
|
87
87
|
Any file can access any value.
|
|
88
88
|
|
|
89
|
-
## After:
|
|
89
|
+
## After: feature-owned environment contracts
|
|
90
90
|
|
|
91
|
-
Move configuration definitions next to the
|
|
91
|
+
Move configuration definitions next to the feature that uses them.
|
|
92
92
|
|
|
93
93
|
Example:
|
|
94
94
|
|
|
@@ -119,7 +119,7 @@ documentEnv(paymentsSchema, {
|
|
|
119
119
|
})
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
-
The
|
|
122
|
+
The feature now owns its requirement:
|
|
123
123
|
|
|
124
124
|
```ts
|
|
125
125
|
import { paymentsEnv } from "./env.schema"
|
|
@@ -157,7 +157,7 @@ DATABASE_URL
|
|
|
157
157
|
|
|
158
158
|
Do not move variables based only on their names. Move them based on the code that consumes them.
|
|
159
159
|
|
|
160
|
-
## Step 2: Create
|
|
160
|
+
## Step 2: Create feature schemas
|
|
161
161
|
|
|
162
162
|
Create schemas alongside existing modules:
|
|
163
163
|
|
|
@@ -175,7 +175,7 @@ src/
|
|
|
175
175
|
│ └── env.schema.ts
|
|
176
176
|
```
|
|
177
177
|
|
|
178
|
-
Each schema defines only the variables required by that
|
|
178
|
+
Each schema defines only the variables required by that feature.
|
|
179
179
|
|
|
180
180
|
## Step 3: Replace direct reads
|
|
181
181
|
|
|
@@ -191,7 +191,7 @@ After:
|
|
|
191
191
|
const apiKey = paymentsEnv.STRIPE_SECRET_KEY
|
|
192
192
|
```
|
|
193
193
|
|
|
194
|
-
The application no longer receives an unknown value. It receives a value that has passed the
|
|
194
|
+
The application no longer receives an unknown value. It receives a value that has passed the feature's validation rules.
|
|
195
195
|
|
|
196
196
|
## Step 4: Add startup validation
|
|
197
197
|
|
|
@@ -264,11 +264,11 @@ The validation remains near the code that understands the variable's purpose.
|
|
|
264
264
|
|
|
265
265
|
A common concern during migration is:
|
|
266
266
|
|
|
267
|
-
> "What if multiple
|
|
267
|
+
> "What if multiple features use the same environment variable?"
|
|
268
268
|
|
|
269
269
|
The answer depends on whether the variable represents the same concept.
|
|
270
270
|
|
|
271
|
-
If multiple
|
|
271
|
+
If multiple features truly share the same configuration meaning:
|
|
272
272
|
|
|
273
273
|
```env
|
|
274
274
|
LOG_LEVEL=info
|
|
@@ -281,13 +281,13 @@ loggingEnv.LOG_LEVEL
|
|
|
281
281
|
apiEnv.LOG_LEVEL
|
|
282
282
|
```
|
|
283
283
|
|
|
284
|
-
If
|
|
284
|
+
If features process the same raw value differently, each feature can define its own contract:
|
|
285
285
|
|
|
286
286
|
```env
|
|
287
287
|
CACHE_TIMEOUT=60000
|
|
288
288
|
```
|
|
289
289
|
|
|
290
|
-
One
|
|
290
|
+
One feature may need:
|
|
291
291
|
|
|
292
292
|
```ts
|
|
293
293
|
cacheEnv.CACHE_TIMEOUT
|
|
@@ -355,7 +355,7 @@ src/
|
|
|
355
355
|
└── env.schema.ts
|
|
356
356
|
```
|
|
357
357
|
|
|
358
|
-
The environment requirements move with the
|
|
358
|
+
The environment requirements move with the features that own them.
|
|
359
359
|
|
|
360
360
|
## When direct process.env usage may be enough
|
|
361
361
|
|
|
@@ -370,12 +370,12 @@ Direct `process.env` access can be appropriate when:
|
|
|
370
370
|
|
|
371
371
|
## Summary
|
|
372
372
|
|
|
373
|
-
Migrating from `process.env` changes configuration from an implicit global dependency into an explicit
|
|
373
|
+
Migrating from `process.env` changes configuration from an implicit global dependency into an explicit feature dependency.
|
|
374
374
|
|
|
375
375
|
Before:
|
|
376
376
|
|
|
377
377
|
```text
|
|
378
|
-
|
|
378
|
+
feature
|
|
379
379
|
|
|
|
380
380
|
v
|
|
381
381
|
process.env.SOME_VARIABLE
|
|
@@ -384,10 +384,10 @@ process.env.SOME_VARIABLE
|
|
|
384
384
|
After:
|
|
385
385
|
|
|
386
386
|
```text
|
|
387
|
-
|
|
387
|
+
feature
|
|
388
388
|
|
|
|
389
389
|
v
|
|
390
|
-
|
|
390
|
+
featureEnv.SOME_VARIABLE
|
|
391
391
|
|
|
|
392
392
|
v
|
|
393
393
|
validated configuration contract
|
|
@@ -32,7 +32,7 @@ This provides:
|
|
|
32
32
|
The difference is architectural:
|
|
33
33
|
|
|
34
34
|
- `t3-env` focuses on **validating an application's environment**.
|
|
35
|
-
- `env-cap` focuses on **organizing configuration ownership across application
|
|
35
|
+
- `env-cap` focuses on **organizing configuration ownership across application features**.
|
|
36
36
|
|
|
37
37
|
Both approaches solve real problems. The correct choice depends on the scale and structure of the application.
|
|
38
38
|
|
|
@@ -59,7 +59,7 @@ src/
|
|
|
59
59
|
|
|
60
60
|
In this structure, a shared environment object is simple and effective.
|
|
61
61
|
|
|
62
|
-
## When
|
|
62
|
+
## When feature ownership becomes important
|
|
63
63
|
|
|
64
64
|
As applications grow, configuration often follows business domains:
|
|
65
65
|
|
|
@@ -75,7 +75,7 @@ src/
|
|
|
75
75
|
└── billing/
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
Each
|
|
78
|
+
Each feature has different owners, deployment concerns, and operational requirements.
|
|
79
79
|
|
|
80
80
|
A centralized environment file becomes a shared coordination point:
|
|
81
81
|
|
|
@@ -93,7 +93,7 @@ env.ts
|
|
|
93
93
|
|
|
94
94
|
The problem is not validation. The problem is ownership.
|
|
95
95
|
|
|
96
|
-
Every
|
|
96
|
+
Every feature change now modifies shared configuration code.
|
|
97
97
|
|
|
98
98
|
## Migration strategy
|
|
99
99
|
|
|
@@ -102,8 +102,8 @@ Migrating from t3-env does not require removing Zod or rewriting validation logi
|
|
|
102
102
|
The recommended migration is:
|
|
103
103
|
|
|
104
104
|
1. Keep existing validation rules.
|
|
105
|
-
2. Move variables into
|
|
106
|
-
3. Replace global `env` imports with
|
|
105
|
+
2. Move variables into feature-owned contracts.
|
|
106
|
+
3. Replace global `env` imports with feature-owned imports.
|
|
107
107
|
4. Add documentation metadata where operational visibility is needed.
|
|
108
108
|
5. Remove the centralized environment object after migration.
|
|
109
109
|
|
|
@@ -134,11 +134,11 @@ import { env } from "@/env"
|
|
|
134
134
|
stripe.connect(env.STRIPE_SECRET_KEY)
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
The
|
|
137
|
+
The feature depends on the application-wide environment object.
|
|
138
138
|
|
|
139
|
-
## After:
|
|
139
|
+
## After: feature-owned env-cap schema
|
|
140
140
|
|
|
141
|
-
Move the configuration requirement into the owning
|
|
141
|
+
Move the configuration requirement into the owning feature:
|
|
142
142
|
|
|
143
143
|
```ts
|
|
144
144
|
// features/payments/env.schema.ts
|
|
@@ -181,7 +181,7 @@ stripe.connect(paymentsEnv.STRIPE_SECRET_KEY)
|
|
|
181
181
|
|
|
182
182
|
The dependency is now explicit.
|
|
183
183
|
|
|
184
|
-
The payments
|
|
184
|
+
The payments feature depends on payments configuration, not the entire application's configuration object.
|
|
185
185
|
|
|
186
186
|
## Reusing Zod validation
|
|
187
187
|
|
|
@@ -207,13 +207,13 @@ const paymentsSchema = {
|
|
|
207
207
|
|
|
208
208
|
The responsibilities become:
|
|
209
209
|
|
|
210
|
-
| Responsibility | Tool
|
|
211
|
-
| ---------------------- |
|
|
212
|
-
| Environment validation | Zod
|
|
213
|
-
|
|
|
214
|
-
| Runtime access |
|
|
215
|
-
| Documentation metadata | `documentEnv()`
|
|
216
|
-
| Project inventory | Build tooling
|
|
210
|
+
| Responsibility | Tool |
|
|
211
|
+
| ---------------------- | ----------------- |
|
|
212
|
+
| Environment validation | Zod |
|
|
213
|
+
| Feature ownership | env-cap |
|
|
214
|
+
| Runtime access | Feature contracts |
|
|
215
|
+
| Documentation metadata | `documentEnv()` |
|
|
216
|
+
| Project inventory | Build tooling |
|
|
217
217
|
|
|
218
218
|
## Migrating client and server variables
|
|
219
219
|
|
|
@@ -298,7 +298,7 @@ export async function createPayment() {
|
|
|
298
298
|
}
|
|
299
299
|
```
|
|
300
300
|
|
|
301
|
-
The
|
|
301
|
+
The feature now declares its own configuration dependency.
|
|
302
302
|
|
|
303
303
|
## Handling shared variables
|
|
304
304
|
|
|
@@ -308,7 +308,7 @@ A centralized environment object assumes one global interpretation:
|
|
|
308
308
|
env.SOME_VARIABLE
|
|
309
309
|
```
|
|
310
310
|
|
|
311
|
-
However, different
|
|
311
|
+
However, different features may require different transformations.
|
|
312
312
|
|
|
313
313
|
Example:
|
|
314
314
|
|
|
@@ -316,7 +316,7 @@ Example:
|
|
|
316
316
|
CACHE_TIMEOUT=60000
|
|
317
317
|
```
|
|
318
318
|
|
|
319
|
-
A caching
|
|
319
|
+
A caching feature may require:
|
|
320
320
|
|
|
321
321
|
```ts
|
|
322
322
|
cacheEnv.CACHE_TIMEOUT
|
|
@@ -325,7 +325,7 @@ cacheEnv.CACHE_TIMEOUT
|
|
|
325
325
|
|
|
326
326
|
because it performs calculations.
|
|
327
327
|
|
|
328
|
-
A monitoring
|
|
328
|
+
A monitoring feature may require:
|
|
329
329
|
|
|
330
330
|
```ts
|
|
331
331
|
monitoringEnv.CACHE_TIMEOUT
|
|
@@ -336,7 +336,7 @@ because it reports configuration values.
|
|
|
336
336
|
|
|
337
337
|
A single global object cannot represent both interpretations without choosing one as the default.
|
|
338
338
|
|
|
339
|
-
|
|
339
|
+
Feature-owned contracts allow each feature to define the meaning it requires.
|
|
340
340
|
|
|
341
341
|
## Generating project-wide visibility
|
|
342
342
|
|
|
@@ -367,7 +367,7 @@ t3-env may remain the better choice when:
|
|
|
367
367
|
|
|
368
368
|
- your application has one configuration owner
|
|
369
369
|
- the centralized schema stays maintainable
|
|
370
|
-
-
|
|
370
|
+
- feature boundaries are not important
|
|
371
371
|
- documentation and lifecycle tracking are handled elsewhere
|
|
372
372
|
|
|
373
373
|
`t3-env` is an excellent validation solution.
|
|
@@ -413,4 +413,4 @@ application
|
|
|
413
413
|
|
|
414
414
|
> "Who owns these environment variables, where are they used, and how do we operate them as the system grows?"
|
|
415
415
|
|
|
416
|
-
The two approaches can also coexist. Existing validation logic can remain while configuration ownership gradually moves closer to the
|
|
416
|
+
The two approaches can also coexist. Existing validation logic can remain while configuration ownership gradually moves closer to the features that depend on it.
|