@maverickcer/env-cap 0.6.0 → 0.7.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 +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -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 +34 -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/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-WKDIAWF7.js} +198 -60
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +194 -56
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +194 -56
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +84 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +83 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +48 -14
- 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-KEGYUHBU.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.
|