@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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +449 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +3 -3
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
|
@@ -0,0 +1,398 @@
|
|
|
1
|
+
# Migrating from direct `process.env` usage
|
|
2
|
+
|
|
3
|
+
Many applications begin by reading environment variables directly from Node's built-in environment object:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
const databaseUrl = process.env.DATABASE_URL
|
|
7
|
+
const stripeKey = process.env.STRIPE_SECRET_KEY
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
This approach is flexible and requires no additional tooling. However, as applications grow, direct `process.env` access creates several challenges:
|
|
11
|
+
|
|
12
|
+
- Environment requirements are scattered throughout the codebase.
|
|
13
|
+
- Validation logic is repeated across capabilities.
|
|
14
|
+
- It is difficult to identify which part of the application owns a variable.
|
|
15
|
+
- Removing unused configuration requires manually searching for references.
|
|
16
|
+
- Platform teams lack a reliable inventory of application configuration.
|
|
17
|
+
|
|
18
|
+
`env-cap` does not replace `process.env`. It creates an ownership and validation layer around it.
|
|
19
|
+
|
|
20
|
+
The relationship is:
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
process.env
|
|
24
|
+
|
|
|
25
|
+
v
|
|
26
|
+
env-cap validation
|
|
27
|
+
|
|
|
28
|
+
v
|
|
29
|
+
capability-owned environment contract
|
|
30
|
+
|
|
|
31
|
+
v
|
|
32
|
+
application code
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Migration goals
|
|
36
|
+
|
|
37
|
+
The recommended migration path is incremental:
|
|
38
|
+
|
|
39
|
+
1. Find existing environment variable usage.
|
|
40
|
+
2. Group variables by the capability that consumes them.
|
|
41
|
+
3. Create capability-owned environment contracts.
|
|
42
|
+
4. Replace direct `process.env` reads with validated access.
|
|
43
|
+
5. Generate project-wide configuration artifacts through build tooling.
|
|
44
|
+
|
|
45
|
+
The goal is not to centralize configuration. The goal is to make ownership explicit.
|
|
46
|
+
|
|
47
|
+
## Before: direct process.env access
|
|
48
|
+
|
|
49
|
+
A typical application:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
// payments/stripe.ts
|
|
53
|
+
|
|
54
|
+
const stripeKey = process.env.STRIPE_SECRET_KEY
|
|
55
|
+
|
|
56
|
+
if (!stripeKey) {
|
|
57
|
+
throw new Error("Missing Stripe key")
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
initializeStripe(stripeKey)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Another module:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
// database/connection.ts
|
|
67
|
+
|
|
68
|
+
const databaseUrl = process.env.DATABASE_URL
|
|
69
|
+
|
|
70
|
+
connect(databaseUrl)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The application works, but configuration ownership is implicit.
|
|
74
|
+
|
|
75
|
+
The environment variables exist globally:
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
process.env
|
|
79
|
+
|
|
80
|
+
├── STRIPE_SECRET_KEY
|
|
81
|
+
├── DATABASE_URL
|
|
82
|
+
├── REDIS_URL
|
|
83
|
+
├── SMTP_PASSWORD
|
|
84
|
+
└── INTERNAL_API_KEY
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Any file can access any value.
|
|
88
|
+
|
|
89
|
+
## After: capability-owned environment contracts
|
|
90
|
+
|
|
91
|
+
Move configuration definitions next to the capability that uses them.
|
|
92
|
+
|
|
93
|
+
Example:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
// features/payments/env.schema.ts
|
|
97
|
+
|
|
98
|
+
import { createEnv, documentEnv } from "@maverickcer/env-cap"
|
|
99
|
+
|
|
100
|
+
const paymentsSchema = {
|
|
101
|
+
STRIPE_SECRET_KEY: {
|
|
102
|
+
validator(value: string) {
|
|
103
|
+
return value.startsWith("sk_") || 'Expected a key starting with "sk_".'
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export const paymentsEnv = createEnv(paymentsSchema, {
|
|
109
|
+
name: "payments",
|
|
110
|
+
})
|
|
111
|
+
|
|
112
|
+
documentEnv(paymentsSchema, {
|
|
113
|
+
owner: "payments-team",
|
|
114
|
+
variables: {
|
|
115
|
+
STRIPE_SECRET_KEY: {
|
|
116
|
+
description: "Stripe API credential used for payment processing",
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The capability now owns its requirement:
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { paymentsEnv } from "./env.schema"
|
|
126
|
+
|
|
127
|
+
initializeStripe(paymentsEnv.STRIPE_SECRET_KEY)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The dependency becomes explicit.
|
|
131
|
+
|
|
132
|
+
A payments module depends on payment configuration instead of depending on an application-wide environment object.
|
|
133
|
+
|
|
134
|
+
## Migrating existing variables
|
|
135
|
+
|
|
136
|
+
### Step 1: Find environment usage
|
|
137
|
+
|
|
138
|
+
Search the application:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
process.env
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Create an inventory:
|
|
145
|
+
|
|
146
|
+
```text
|
|
147
|
+
STRIPE_SECRET_KEY
|
|
148
|
+
used by:
|
|
149
|
+
- features/payments
|
|
150
|
+
- scripts/refund-job
|
|
151
|
+
|
|
152
|
+
DATABASE_URL
|
|
153
|
+
used by:
|
|
154
|
+
- database module
|
|
155
|
+
- migrations
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Do not move variables based only on their names. Move them based on the code that consumes them.
|
|
159
|
+
|
|
160
|
+
## Step 2: Create capability schemas
|
|
161
|
+
|
|
162
|
+
Create schemas alongside existing modules:
|
|
163
|
+
|
|
164
|
+
```text
|
|
165
|
+
src/
|
|
166
|
+
|
|
167
|
+
├── features/
|
|
168
|
+
│ ├── payments/
|
|
169
|
+
│ │ └── env.schema.ts
|
|
170
|
+
│ │
|
|
171
|
+
│ ├── notifications/
|
|
172
|
+
│ │ └── env.schema.ts
|
|
173
|
+
│ │
|
|
174
|
+
│ └── reporting/
|
|
175
|
+
│ └── env.schema.ts
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Each schema defines only the variables required by that capability.
|
|
179
|
+
|
|
180
|
+
## Step 3: Replace direct reads
|
|
181
|
+
|
|
182
|
+
Before:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
const apiKey = process.env.STRIPE_SECRET_KEY
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
After:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const apiKey = paymentsEnv.STRIPE_SECRET_KEY
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The application no longer receives an unknown value. It receives a value that has passed the capability's validation rules.
|
|
195
|
+
|
|
196
|
+
## Step 4: Add startup validation
|
|
197
|
+
|
|
198
|
+
Generate a manifest:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
await generateEnvManifest({
|
|
202
|
+
location: "src/generated/env.manifest.ts",
|
|
203
|
+
})
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Validate once during startup:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
import { validateEnv } from "@maverickcer/env-cap"
|
|
210
|
+
import { manifest } from "./generated/env.manifest"
|
|
211
|
+
|
|
212
|
+
await validateEnv({
|
|
213
|
+
manifest,
|
|
214
|
+
values: process.env,
|
|
215
|
+
})
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
After validation:
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
paymentsEnv.STRIPE_SECRET_KEY
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
returns the processed value.
|
|
225
|
+
|
|
226
|
+
Before validation completes:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
paymentsEnv.STRIPE_SECRET_KEY
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
throws an `EnvNotReadyError`.
|
|
233
|
+
|
|
234
|
+
## Handling existing validation logic
|
|
235
|
+
|
|
236
|
+
Many applications already have inline validation:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
const port = Number(process.env.PORT)
|
|
240
|
+
|
|
241
|
+
if (Number.isNaN(port)) {
|
|
242
|
+
throw new Error("Invalid PORT")
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Move that logic into the contract:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
const serverSchema = {
|
|
250
|
+
PORT: {
|
|
251
|
+
processor(value: string) {
|
|
252
|
+
return Number(value)
|
|
253
|
+
},
|
|
254
|
+
validator(value: number) {
|
|
255
|
+
return (Number.isInteger(value) && value > 0) || "Expected a positive integer."
|
|
256
|
+
},
|
|
257
|
+
},
|
|
258
|
+
}
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The validation remains near the code that understands the variable's purpose.
|
|
262
|
+
|
|
263
|
+
## Handling shared environment variables
|
|
264
|
+
|
|
265
|
+
A common concern during migration is:
|
|
266
|
+
|
|
267
|
+
> "What if multiple capabilities use the same environment variable?"
|
|
268
|
+
|
|
269
|
+
The answer depends on whether the variable represents the same concept.
|
|
270
|
+
|
|
271
|
+
If multiple capabilities truly share the same configuration meaning:
|
|
272
|
+
|
|
273
|
+
```env
|
|
274
|
+
LOG_LEVEL=info
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
multiple contracts may reference it:
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
loggingEnv.LOG_LEVEL
|
|
281
|
+
apiEnv.LOG_LEVEL
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
If capabilities process the same raw value differently, each capability can define its own contract:
|
|
285
|
+
|
|
286
|
+
```env
|
|
287
|
+
CACHE_TIMEOUT=60000
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
One capability may need:
|
|
291
|
+
|
|
292
|
+
```ts
|
|
293
|
+
cacheEnv.CACHE_TIMEOUT
|
|
294
|
+
// number
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
while another may need:
|
|
298
|
+
|
|
299
|
+
```ts
|
|
300
|
+
monitoringEnv.CACHE_TIMEOUT
|
|
301
|
+
// string for reporting
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
A centralized object would have to choose one global interpretation. Feature-owned contracts keep processing decisions local.
|
|
305
|
+
|
|
306
|
+
## Coexisting with existing environment files
|
|
307
|
+
|
|
308
|
+
`env-cap` does not require changing how environments are provided.
|
|
309
|
+
|
|
310
|
+
Existing systems continue to work:
|
|
311
|
+
|
|
312
|
+
```text
|
|
313
|
+
Docker
|
|
314
|
+
|
|
|
315
|
+
Kubernetes
|
|
316
|
+
|
|
|
317
|
+
Cloud provider secrets
|
|
318
|
+
|
|
|
319
|
+
CI/CD variables
|
|
320
|
+
|
|
|
321
|
+
process.env
|
|
322
|
+
|
|
|
323
|
+
env-cap
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The package validates and organizes values after they enter the application process.
|
|
327
|
+
|
|
328
|
+
## Removing the old environment object
|
|
329
|
+
|
|
330
|
+
After migration:
|
|
331
|
+
|
|
332
|
+
Before:
|
|
333
|
+
|
|
334
|
+
```text
|
|
335
|
+
src/
|
|
336
|
+
|
|
337
|
+
├── env.ts
|
|
338
|
+
│ ├── DATABASE_URL
|
|
339
|
+
│ ├── STRIPE_SECRET_KEY
|
|
340
|
+
│ └── REDIS_URL
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
After:
|
|
344
|
+
|
|
345
|
+
```text
|
|
346
|
+
src/
|
|
347
|
+
|
|
348
|
+
├── database/
|
|
349
|
+
│ └── env.schema.ts
|
|
350
|
+
│
|
|
351
|
+
├── payments/
|
|
352
|
+
│ └── env.schema.ts
|
|
353
|
+
│
|
|
354
|
+
└── cache/
|
|
355
|
+
└── env.schema.ts
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
The environment requirements move with the capabilities that own them.
|
|
359
|
+
|
|
360
|
+
## When direct process.env usage may be enough
|
|
361
|
+
|
|
362
|
+
Direct `process.env` access can be appropriate when:
|
|
363
|
+
|
|
364
|
+
- the application is small
|
|
365
|
+
- there are few environment variables
|
|
366
|
+
- configuration ownership is obvious
|
|
367
|
+
- validation requirements are minimal
|
|
368
|
+
|
|
369
|
+
`env-cap` is intended for applications where configuration management becomes a coordination problem between developers and platform teams.
|
|
370
|
+
|
|
371
|
+
## Summary
|
|
372
|
+
|
|
373
|
+
Migrating from `process.env` changes configuration from an implicit global dependency into an explicit capability dependency.
|
|
374
|
+
|
|
375
|
+
Before:
|
|
376
|
+
|
|
377
|
+
```text
|
|
378
|
+
capability
|
|
379
|
+
|
|
|
380
|
+
v
|
|
381
|
+
process.env.SOME_VARIABLE
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
After:
|
|
385
|
+
|
|
386
|
+
```text
|
|
387
|
+
capability
|
|
388
|
+
|
|
|
389
|
+
v
|
|
390
|
+
capabilityEnv.SOME_VARIABLE
|
|
391
|
+
|
|
|
392
|
+
v
|
|
393
|
+
validated configuration contract
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`process.env` remains the source of configuration values.
|
|
397
|
+
|
|
398
|
+
`env-cap` provides the structure needed to safely manage those values as applications and teams scale.
|