The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Provider docs |
| 2 | |
| 3 | A provider ships two kinds of docs, and both have a bar: |
| 4 | |
| 5 | - **The API reference**, generated from JSDoc by `pnpm docs:gen` into |
| 6 | `website/src/content/docs/providers/<P>/`. Never edit it by hand. |
| 7 | - **The hub**, hand-written pages under |
| 8 | `website/src/content/docs/<provider>/`. |
| 9 | |
| 10 | ## API reference (JSDoc) |
| 11 | |
| 12 | The generated reference page is the first thing a user reads about a |
| 13 | resource, and it is only as good as the JSDoc on the source. The bar |
| 14 | depends on how much the resource is used. Compare every runtime and |
| 15 | fat-head resource side by side with its AWS or Cloudflare counterpart |
| 16 | before you call it done. |
| 17 | |
| 18 | Azure missed this bar. `Azure.Functions.Function` shipped with two |
| 19 | examples, an HTTP handler and a schedule, while `AWS.Lambda.Function` |
| 20 | has 21 across eleven sections. Its fat-head resources had 2–5 examples |
| 21 | each, against 10–21 for S3 Bucket, SQS Queue and R2 Bucket. |
| 22 | |
| 23 | ### Runtimes |
| 24 | |
| 25 | Copy the shape of `packages/aws/src/Lambda/Function.ts` and |
| 26 | `packages/cloudflare/src/Workers/Worker.ts`. A runtime's JSDoc has: |
| 27 | |
| 28 | - **An intro** that says what the runtime is, what Alchemy creates and |
| 29 | owns for you (role or identity, registry, plan), what it does not own, |
| 30 | and the forms it takes (async, Effect, image). Link to the hub's |
| 31 | compute page. |
| 32 | - **`:::caution` callouts** for platform behavior that will bite |
| 33 | (finalizers and response timing, cold starts, read-only file systems, |
| 34 | size limits), each with a link to the hub page that explains it. |
| 35 | - **One section per form**: `### Async …` with the stack declaration and |
| 36 | the handler file, `### Effect …` with a construction/runtime split, and |
| 37 | a section for container images if the runtime takes them. |
| 38 | - **`### Configuration`**: one example per common setup (public URL and |
| 39 | its auth, networking, scaling and concurrency, retries and failure |
| 40 | destinations, architecture, environment). |
| 41 | - **Packaging**: bundling options and native packages, or the Dockerfile |
| 42 | contract. |
| 43 | - **One `### <Service> Bindings` section per service** with bindings the |
| 44 | runtime uses (storage, database, queue, topic, secrets), each showing |
| 45 | the binding in construction and its call at runtime. |
| 46 | - **`### Event Sources`**: one example per trigger the runtime supports. |
| 47 | - **Storage mounts, networking, and other attachments** the runtime |
| 48 | supports, one section each. |
| 49 | |
| 50 | Aim for ten or more examples. If you have fewer, find which section is |
| 51 | missing. |
| 52 | |
| 53 | ### Fat-head resources |
| 54 | |
| 55 | The 10–20 resources most apps use (see the PR description in step 10). |
| 56 | Copy `packages/aws/src/S3/Bucket.ts`, `packages/aws/src/SQS/Queue.ts` |
| 57 | and `packages/cloudflare/src/R2/Bucket.ts`: |
| 58 | |
| 59 | - **An intro**: what it is in user terms, the secure defaults Alchemy |
| 60 | applies, and what replacing it costs (data loss, downtime). |
| 61 | - **`### Creating …`**: the minimal declaration, then the common |
| 62 | variants (sizes, tiers, regions, serverless vs provisioned). |
| 63 | - **One section per feature users configure**: encryption, lifecycle or |
| 64 | retention, CORS, dead-letter queues, custom domains, networking, |
| 65 | backups, scaling. Each is a heading with one or more examples. |
| 66 | - **`### Binding to a runtime`**: the binding inside a host, with its |
| 67 | `Effect.provide(...)` layer, and the role or grant it gives. |
| 68 | - **`### Runtime operations`**: the calls users make through the binding. |
| 69 | - **`### Event sources`** when the resource triggers runtimes. |
| 70 | - **Adoption and deletion** when they behave in a way users must know |
| 71 | (`forceDestroy`, retained data, soft delete, name reuse windows). |
| 72 | |
| 73 | Aim for five sections or more. |
| 74 | |
| 75 | ### Long tail |
| 76 | |
| 77 | Everything else gets, at minimum: |
| 78 | |
| 79 | - An intro naming the cloud's resource type (the ARM type, API resource, |
| 80 | or console name), what it's for, and a docs link. |
| 81 | - One realistic creation example that declares or names every value it |
| 82 | uses. |
| 83 | - A `:::caution` for each prop whose change replaces the resource, and |
| 84 | for each prerequisite a fresh account trips on (a feature to register, |
| 85 | a quota, a parent resource that must exist). |
| 86 | |
| 87 | ### Every page |
| 88 | |
| 89 | - Every prop and attribute has JSDoc with its unit, allowed values, |
| 90 | `@default`, and whether changing it replaces the resource. |
| 91 | - Every snippet either declares what it uses or is clearly a fragment |
| 92 | inside a host (`// init` and `// runtime` comments, as on Lambda). |
| 93 | - Every `@binding` example shows the host and its `Effect.provide(...)` |
| 94 | layer. |
| 95 | - Section headings are `###`, examples are `**Example:**`, and the |
| 96 | generator tags (`@resource`, `@binding`, `@category`, …) come last; |
| 97 | run `pnpm docs:check-jsdoc`. |
| 98 | |
| 99 | ## The hub |
| 100 | |
| 101 | The hub copies the AWS hub (`website/src/content/docs/aws/`), not the |
| 102 | order the provider was built in. GCP's first hub was four long "guides" |
| 103 | that walked the examples end to end. It had no tutorial, no per-service |
| 104 | pages, prose that narrated internals, and snippets without imports. It |
| 105 | was rebuilt to match AWS in alchemy-run/alchemy#2374. Use the rebuilt |
| 106 | GCP hub (`website/src/content/docs/gcp/`) as the model, and compare each |
| 107 | page with its AWS sibling before you write it. |
| 108 | |
| 109 | ### Structure |
| 110 | |
| 111 | ``` |
| 112 | <P> |
| 113 | ├─ Overview · Setup |
| 114 | ├─ Tutorial Part 1–5: first resource → first runtime → Testing → Stages → CI/CD |
| 115 | ├─ Compute Choosing a runtime · one page per runtime |
| 116 | ├─ Frontend Overview (websites) + one page per framework |
| 117 | ├─ APIs Effect HTTP · Effect RPC |
| 118 | ├─ Data one page per database / storage service |
| 119 | ├─ AI one page per AI service |
| 120 | ├─ Messaging one page per queue / topic / event source |
| 121 | ├─ Security IAM & bindings · secrets and keys |
| 122 | ├─ Observability logging and monitoring |
| 123 | └─ Networking networks, private services, custom domains |
| 124 | ``` |
| 125 | |
| 126 | Leave out a section only when the provider has nothing for it, and pick |
| 127 | section names that fit the provider: a section name must tell its pages |
| 128 | apart from the rest of the hub, so a database-only provider has no |
| 129 | "Data" section. Every page except Overview and Setup sits in a section. |
| 130 | There is no `guides/` directory. |
| 131 | |
| 132 | | Path | Content | |
| 133 | | --- | --- | |
| 134 | | `index.mdx` | Overview: one sentence on what the user gets, one complete runtime-plus-binding snippet, links to Setup and the tutorial, then a link list per section | |
| 135 | | `setup.mdx` | credentials, the profile command, CI env vars | |
| 136 | | `tutorial/part-1.mdx` … `part-5.mdx` | the same five parts as AWS: "Your First Stack" (one storage resource), "Add a <Runtime>" (bind it, GET/PUT routes), "Testing", "Stages", "CI/CD" (the cloud's keyless CI auth, e.g. OIDC or Workload Identity Federation) | |
| 137 | | `compute/choosing-a-runtime.mdx` | one line per runtime, then a table comparing entry point, triggers, cost, packaging, and deploy time | |
| 138 | | `compute/<runtime>.mdx` | one per runtime the provider hosts | |
| 139 | | `frontend/websites.mdx` + `frontend/<framework>.mdx` | one per `<P>.Website.<Framework>` (step 7), same file names as `aws/frontend/` | |
| 140 | | `apis/effect-http-api.mdx`, `apis/effect-rpc.mdx` | Effect HTTP and RPC servers on the default runtime | |
| 141 | | `<section>/<service>.mdx` | one page per service a user builds with | |
| 142 | |
| 143 | ### Every hub page |
| 144 | |
| 145 | - **Code comes from what's tested**: the `examples/<provider>-*` projects |
| 146 | and the resource JSDoc examples. If a page needs code no example has, |
| 147 | add it to an example and deploy it first. |
| 148 | - **Whole files.** Every block with `import` lines is a complete file |
| 149 | with a `// path` comment on its first line. No `...` elisions, no |
| 150 | `yield*` at module scope. Declare resources as module-scope consts and |
| 151 | pass the declaration straight to bindings and props. |
| 152 | - **Small steps.** Each `##` heading does one thing: one or two short |
| 153 | lines, then the snippet. A follow-up change is a `diff lang="typescript"` |
| 154 | block whose first line is a column-0 context line (the `// path` |
| 155 | comment), or the website build rejects it. |
| 156 | - **Talk to the reader.** Second person, present tense, an instruction or |
| 157 | something they'll see: "Run `alchemy deploy`. `site.url` is the service |
| 158 | URL." Don't narrate what Alchemy does inside, why a limitation exists, |
| 159 | or the docs' own structure ("this page", "Part 3 is where"). Use plain |
| 160 | words: create, not mint/provision. |
| 161 | - **State the grant.** Every binding section says which role it grants |
| 162 | and that it only covers the bound resource. |
| 163 | - **No dumps.** No "three ideas" framing, no bullet lists explaining one |
| 164 | snippet (split it into headings), no whole-file embeds as explanation. |
| 165 | Tables only where they map things, like the runtime comparison. |
| 166 | - **Frontmatter**: `title` and a one-sentence `description` that says |
| 167 | what the reader does on the page. Tutorial parts add `sidebar.order`. |
| 168 | |
| 169 | A data or messaging page follows `gcp/data/firestore.mdx`: create the |
| 170 | resource, bind it to a service with the Read/Write/ReadWrite choice and |
| 171 | the role it grants, then one heading per operation (read, write, update, |
| 172 | query, delete), each a short block inside the handler. |
| 173 | |
| 174 | A framework page follows `gcp/frontend/astro.mdx`: install the build |
| 175 | integration as a dev dependency (`<PackageManagers dev=… />`), deploy the |
| 176 | site from `alchemy.run.ts`, then one heading per option (env, assets, |
| 177 | domain, `alchemy dev`). |
| 178 | |
| 179 | ### Wiring |
| 180 | |
| 181 | - `website/astro.config.ts`: the hub's sidebar. Overview, Setup, |
| 182 | `Tutorial` (autogenerated from `<provider>/tutorial`), one group per |
| 183 | section, `sortFrontendItems([...])` for Frontend, and |
| 184 | `providerResourcesEntry("<P>")` last. |
| 185 | - `website/src/docs-icons.ts`: every new section label has an icon in |
| 186 | `GROUP_ICONS`. |
| 187 | - `website/src/docs-tabs.ts` and |
| 188 | `website/src/components/ProviderDirectory.astro`: the hub's tab and its |
| 189 | card. |
| 190 | - `website/scripts/generate-llms-txt.ts`: a "start here" section |
| 191 | (`<provider>/index`, `<provider>/setup`), then one |
| 192 | `{ heading: "<P> — <Section>", pages: { directory: "<provider>/<section>" } }` |
| 193 | per section. |
| 194 | - `website/src/worker.ts` `REDIRECTS`: when a page moves or is removed, |
| 195 | map the old path to its closest new page. |
| 196 | |
| 197 | ## Check |
| 198 | |
| 199 | ```sh |
| 200 | pnpm docs:check-jsdoc && pnpm docs:gen |
| 201 | pnpm docs:check # builds the website, including the diff-block and link checks |
| 202 | ``` |
| 203 | |
| 204 | Then read the hub next to AWS's sidebar: every AWS section either has a |
| 205 | `<P>` counterpart or the provider has nothing for it. |