@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, 07:15 UTC

main
md 205 lines 9.89 KB
Rendered Raw
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.