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

main
mdx 183 lines 5.55 KB
Raw
1 ---
2 title: Provider Contributions
3 description: Ship a provider's auth, state stores and CLI commands in a package, so the alchemy CLI finds them without a stack.
4 ---
5
6 Some of a provider runs before any stack is loaded: `alchemy profile`
7 configures its credentials, `alchemy state --backend` opens its state
8 store, and `alchemy provider <name>` runs its commands. A provider
9 package declares these in a **contributions** module, and the CLI reads it
10 from the project's dependencies.
11
12 This guide packages the Stripe provider from
13 [Custom Provider](/infrastructure-as-code/custom-provider) and
14 [Custom Auth Provider](/environments/custom-auth-provider) as
15 `@acme/alchemy-stripe`.
16
17 ## Declare the module
18
19 List the module under `alchemy.contributes` in the package's
20 `package.json`, and export it:
21
22 ```json
23 {
24 "name": "@acme/alchemy-stripe",
25 "exports": {
26 ".": "./src/index.ts",
27 "./Contributions": "./src/Contributions.ts"
28 },
29 "alchemy": { "contributes": ["@acme/alchemy-stripe/Contributions"] }
30 }
31 ```
32
33 A specifier must name the package that declares it. It resolves through
34 that package's `exports`.
35
36 ## Name the provider
37
38 The module's default export is the provider's contributions:
39
40 ```typescript
41 // src/Contributions.ts
42 import * as Contributions from "alchemy/Contributions";
43
44 export default Contributions.make({
45 name: "stripe",
46 });
47 ```
48
49 `name` identifies the provider: it's the subcommand in
50 `alchemy provider stripe`.
51
52 ## Load fields lazily
53
54 The CLI imports every contributions module on start, so a field points
55 at code instead of importing it. `Contributions.lazy` imports a module
56 the first time the field is used:
57
58 ```diff lang="typescript"
59 export default Contributions.make({
60 name: "stripe",
61 + auth: Contributions.lazy(
62 + () => import("./AuthProvider.ts"),
63 + (module) => module.StripeAuth,
64 + ),
65 });
66 ```
67
68 `auth` is the Auth Provider layer. With it, `alchemy profile edit` can
69 configure Stripe credentials in a project whose stack hasn't run yet.
70
71 ## Add a CLI command
72
73 `cli.provider` adds a subcommand under `alchemy provider`. The
74 description shows in `--help` without loading the command:
75
76 ```diff lang="typescript"
77 + cli: {
78 + provider: {
79 + description: "Manage Stripe prerequisites",
80 + load: Contributions.lazy(
81 + () => import("./Cli.ts"),
82 + (module) => module.stripeCommand,
83 + ),
84 + },
85 + },
86 ```
87
88 `stripeCommand` is an `effect/cli` `Command` named `stripe`. A provider
89 whose command fails to load doesn't break the others: running it reports
90 the error.
91
92 ## Add a state store
93
94 `stateStores` maps a `--backend` name to a store:
95
96 ```diff lang="typescript"
97 + stateStores: {
98 + stripe: {
99 + description: "State in the profile's Stripe account",
100 + load: Contributions.lazy(
101 + () => import("./StateStore.ts"),
102 + (module) => module.stateStore,
103 + ),
104 + },
105 + },
106 ```
107
108 The store's `layer` is the provider's own `state` function: the one a
109 stack passes as `state:`.
110
111 ```typescript
112 // src/StateStore.ts
113 import type { StateStoreImpl } from "alchemy/Contributions";
114 import { state } from "./State.ts";
115
116 export const stateStore: StateStoreImpl = { layer: state };
117 ```
118
119 `state` takes `{ name }` and returns a `State` layer. A missing `name` is the
120 account's default store, and any other name is a separate store. With
121 the store contributed, `alchemy state list --backend stripe --name team-a`
122 opens it from the profile alone.
123
124 ## Add a store lifecycle
125
126 A store that needs provisioning adds a `lifecycle`. Each operation is
127 optional, and `alchemy state` reports the ones a store doesn't have:
128
129 ```diff lang="typescript"
130 -export const stateStore: StateStoreImpl = { layer: state };
131 +export const stateStore: StateStoreImpl = {
132 + layer: state,
133 + lifecycle: { bootstrap, teardown },
134 +};
135 ```
136
137 | Operation | Runs for |
138 | ----------- | ---------------------------- |
139 | `bootstrap` | `alchemy state bootstrap` |
140 | `teardown` | `alchemy state teardown` |
141 | `logs` | `alchemy state logs` |
142 | `tailLogs` | `alchemy state logs --tail` |
143
144 Each operation receives the store's `name`, and Alchemy provides the
145 profile's config and the provider's `auth`. The built-in stores are
146 the reference:
147 [`AWS/Alchemist/StateStore.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/alchemy/src/AWS/Alchemist/StateStore.ts)
148 and
149 [`Cloudflare/Alchemist/StateStore.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/cloudflare/src/Alchemist/StateStore.ts).
150
151 ## What contributed code can use
152
153 Every host of contributed code provides the same services:
154 `Contributions.ContributionServices` for auth and state stores (platform,
155 HTTP client, profiles, credentials, the auth registry), and
156 `Contributions.CliServices` for commands (those plus the terminal). A
157 field that needs anything else doesn't type-check. Provide it in the
158 field's own layer:
159
160 ```typescript
161 auth: Contributions.lazy(
162 () => import("./AuthProvider.ts"),
163 (module) => module.StripeAuth.pipe(Layer.provide(StripeHttpClient)),
164 ),
165 ```
166
167 ## How the CLI picks providers
168
169 - The project's dependencies are read first, then alchemy's own
170 providers.
171 - When two providers share a name, the first one found is used. A
172 provider in its own package therefore replaces the copy still inside
173 alchemy.
174 - A provider that fails to load is skipped with a warning.
175 - State store names are global. Two providers contributing the same
176 name, or `local` or `configured`, is an error.
177
178 ## Where next
179
180 - [Custom Auth Provider](/environments/custom-auth-provider): the
181 `auth` layer
182 - [`alchemy state`](/cli/state): the commands a state store serves
183 - [State Store](/state-store): where resource state lives