sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ infrastructure-as-code/ contributions.mdx

Some of a provider runs before any stack is loaded: alchemy profile configures its credentials, alchemy state --backend opens its state store, and alchemy provider <name> runs its commands. A provider package declares these in a contributions module, and the CLI reads it from the project's dependencies.

This guide packages the Stripe provider from Custom Provider and Custom Auth Provider as @acme/alchemy-stripe.

Declare the module

List the module under alchemy.contributes in the package's package.json, and export it:

{
  "name": "@acme/alchemy-stripe",
  "exports": {
    ".": "./src/index.ts",
    "./Contributions": "./src/Contributions.ts"
  },
  "alchemy": { "contributes": ["@acme/alchemy-stripe/Contributions"] }
}

A specifier must name the package that declares it. It resolves through that package's exports.

Name the provider

The module's default export is the provider's contributions:

// src/Contributions.ts
import * as Contributions from "alchemy/Contributions";

export default Contributions.make({
  name: "stripe",
});

name identifies the provider: it's the subcommand in alchemy provider stripe.

Load fields lazily

The CLI imports every contributions module on start, so a field points at code instead of importing it. Contributions.lazy imports a module the first time the field is used:

 export default Contributions.make({
   name: "stripe",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.StripeAuth,
+  ),
 });

auth is the Auth Provider layer. With it, alchemy profile edit can configure Stripe credentials in a project whose stack hasn't run yet.

Add a CLI command

cli.provider adds a subcommand under alchemy provider. The description shows in --help without loading the command:

+  cli: {
+    provider: {
+      description: "Manage Stripe prerequisites",
+      load: Contributions.lazy(
+        () => import("./Cli.ts"),
+        (module) => module.stripeCommand,
+      ),
+    },
+  },

stripeCommand is an effect/cli Command named stripe. A provider whose command fails to load doesn't break the others: running it reports the error.

Add a state store

stateStores maps a --backend name to a store:

+  stateStores: {
+    stripe: {
+      description: "State in the profile's Stripe account",
+      load: Contributions.lazy(
+        () => import("./StateStore.ts"),
+        (module) => module.stateStore,
+      ),
+    },
+  },

The store's layer is the provider's own state function: the one a stack passes as state:.

// src/StateStore.ts
import type { StateStoreImpl } from "alchemy/Contributions";
import { state } from "./State.ts";

export const stateStore: StateStoreImpl = { layer: state };

state takes { name } and returns a State layer. A missing name is the account's default store, and any other name is a separate store. With the store contributed, alchemy state list --backend stripe --name team-a opens it from the profile alone.

Add a store lifecycle

A store that needs provisioning adds a lifecycle. Each operation is optional, and alchemy state reports the ones a store doesn't have:

-export const stateStore: StateStoreImpl = { layer: state };
+export const stateStore: StateStoreImpl = {
+  layer: state,
+  lifecycle: { bootstrap, teardown },
+};
OperationRuns for
bootstrapalchemy state bootstrap
teardownalchemy state teardown
logsalchemy state logs
tailLogsalchemy state logs --tail

Each operation receives the store's name, and Alchemy provides the profile's config and the provider's auth. The built-in stores are the reference: AWS/Alchemist/StateStore.ts and Cloudflare/Alchemist/StateStore.ts.

What contributed code can use

Every host of contributed code provides the same services: Contributions.ContributionServices for auth and state stores (platform, HTTP client, profiles, credentials, the auth registry), and Contributions.CliServices for commands (those plus the terminal). A field that needs anything else doesn't type-check. Provide it in the field's own layer:

auth: Contributions.lazy(
  () => import("./AuthProvider.ts"),
  (module) => module.StripeAuth.pipe(Layer.provide(StripeHttpClient)),
),

How the CLI picks providers

  • The project's dependencies are read first, then alchemy's own providers.
  • When two providers share a name, the first one found is used. A provider in its own package therefore replaces the copy still inside alchemy.
  • A provider that fails to load is skipped with a warning.
  • State store names are global. Two providers contributing the same name, or local or configured, is an error.

Where next