@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 136 lines 4.73 KB
Raw
1 ---
2 title: Secret providers
3 description: Configure a stack with dotenv files, environment variables, Doppler, or Infisical.
4 ---
5
6 Set the optional `secrets` field to choose where a stack's Effect `Config`
7 values come from: one provider or an ordered list. Omitting it preserves
8 existing configuration, including any injected `ConfigProvider`. The CLI
9 normally reads the process environment with `.env` as a fallback; an
10 explicit `--env-file` takes precedence over the process environment.
11
12 ```typescript
13 import * as Doppler from "@alchemy.run/doppler";
14
15 export default Alchemy.Stack(
16 "MyApp",
17 {
18 providers: Cloudflare.providers(),
19 state: Cloudflare.state(),
20 secrets: [
21 Doppler.Secrets({ project: "my-app", config: "dev" }),
22 Alchemy.Secrets.DotEnv(),
23 ],
24 },
25 Effect.gen(function* () {
26 const dbUrl = yield* Config.Redacted("DATABASE_URL");
27 // ...
28 }),
29 );
30 ```
31
32 ## Precedence
33
34 Later entries override earlier ones. In the example above, process
35 environment variables override `.env`, which overrides Doppler.
36
37 The process environment is the implicit last entry, so a one-off
38 `DATABASE_URL=... alchemy deploy` and a CI runner's exported tokens
39 work with any list. List `Secrets.ProcessEnv()` yourself to rank it
40 elsewhere, typically first so it is only a fallback for what the
41 secrets manager holds:
42
43 ```typescript
44 secrets: [
45 Alchemy.Secrets.ProcessEnv(),
46 Doppler.Secrets({ project: "my-app", config: "prd" }),
47 ],
48 ```
49
50 `Secrets.ProcessEnv({ disabled: true })` leaves the shell out
51 entirely. Cloud credentials such as `CLOUDFLARE_API_TOKEN` go through
52 the same list, so with the shell disabled they must come from a
53 provider. A secrets manager's own credentials are the exception: it
54 reads `DOPPLER_TOKEN`, `INFISICAL_IDENTITY_ID`, and `CI` from the
55 process environment only, whatever the list says, so a runner's
56 exported variables always reach it and no file can impersonate them.
57
58 For stacks that declare `secrets`, one key is exempt: `ALCHEMY_PROFILE`. Which
59 [profile](/environments/profiles) a deploy authenticates with comes
60 from `--profile` or the real process environment only, so no provider
61 can redirect the credentials every other provider uses.
62
63 ## Per stage
64
65 Both the `secrets` option and every provider's options accept a
66 callback instead of a value. It receives the
67 [stage](/environments/stages), the stack, and the Alchemy context, so
68 one stack definition serves `dev`, `pr-42`, and `prod` from different
69 places:
70
71 ```typescript
72 secrets: ({ stage }) =>
73 stage === "dev"
74 ? Alchemy.Secrets.DotEnv()
75 : Doppler.Secrets({ project: "my-app", config: stage }),
76 ```
77
78 The same shape narrows a single provider:
79
80 ```typescript
81 secrets: [
82 Alchemy.Secrets.DotEnv(({ stage }) => ({ path: [".env", `.env.${stage}`] })),
83 ],
84 ```
85
86 ## Dotenv details
87
88 `Secrets.DotEnv` reads one file or an ordered list. The implicit
89 default `.env` may be absent; a file you name must exist. Empty
90 values are real values and override earlier files. Pass
91 `expandVariables: true` to expand `${OTHER}` references.
92
93 Nothing is written to `process.env`. Values live in Effect's
94 [ConfigProvider](https://effect.website/docs/configuration/), so two
95 stacks in one process never see each other's files.
96
97 `--env-file` retains its existing behavior when `secrets` is omitted.
98 It is refused when the stack declares `secrets`; put
99 `Secrets.DotEnv({ path })` in the list instead.
100
101 ## Seeing what loaded
102
103 With `--log-level debug`, dotenv, Doppler, and Infisical report the
104 variable names they loaded, never their values. The process environment
105 reports only a count. These messages describe loaded sources; process
106 environment overrides and custom layers can still change the final values.
107
108 ```text
109 Loaded 3 secrets from dotenv (.env, .env.prod): DATABASE_URL, PORT, SENTRY_DSN
110 Loaded 12 secrets from Doppler (project 'app' config 'prd'): API_KEY, DATABASE_URL, ...
111 Loaded 87 secrets from the process environment
112 ```
113
114 ## Bring your own source
115
116 Any Effect `Layer` that provides a `ConfigProvider` is a valid entry.
117 Use `ConfigProvider.layerAdd` with `asPrimary` to merge with what
118 came before, the way the built-in providers do; a plain
119 `ConfigProvider.layer` replaces everything listed before it:
120
121 ```typescript
122 secrets: [
123 ConfigProvider.layerAdd(ConfigProvider.fromUnknown(defaults), { asPrimary: true }),
124 Alchemy.Secrets.DotEnv(),
125 ],
126 ```
127
128 The Doppler and Infisical providers skip remote loading during
129 [auth-provider discovery](/environments/auth-providers), which builds
130 the stack offline just to find out which clouds it uses.
131
132 ## Where next
133
134 - [Doppler](/environments/doppler) — browser login locally, service tokens in CI.
135 - [Infisical](/environments/infisical) — machine identities locally, platform OIDC in CI.
136 - [Secrets & Config](/environments/secrets) — how a `Config` value ends up bound to a Worker or Lambda.