Don't want to fix it yourself?

Check out Manicule.

Visit Manicule

Report/Jul 10

Alchemy

alchemy.run

Manicule Score

87

0100

Pages read20

Critical2

Significant2

Minor3

Surfacev2.alchemy.run

Verdict

“the same bucket goes by three different names depending on which page you copied your code from”

Share on XImage

Alchemy (v2) Documentation Audit

Ambitious, often well-written docs for a pre-release Infrastructure-as-Effects framework — undermined by API-shape drift between pages, a state-property contradiction that makes the flagship intro examples fail the tutorial's own type check, and a parallel v1 docs universe (alchemy.run + the GitHub README) that never points here.

1. Three incompatible API shapes for the same resource across core pages (critical)

Location: https://v2.alchemy.run/what-is-alchemy/ vs https://v2.alchemy.run/getting-started/, /cloudflare/tutorial/part-1/, /migrating-from-v1/, /infrastructure-as-code/resource/

Problem: The docs use three different, mutually incompatible spellings for the same R2 bucket API. The "What is Alchemy?" page declares resources flat — Cloudflare.R2Bucket("Bucket"), Cloudflare.D1Database("DB") — and binds with Cloudflare.R2Bucket.bind(Bucket). Getting Started, Tutorial Part 1, Migrating from v1, and the Resource concept page all use the namespaced form Cloudflare.R2.Bucket("Bucket"). The migration guide then binds with yet another form: Cloudflare.R2.ReadWriteBucket(Bucket). Only one of these can match the actual alchemy@next exports; the others are code that will not compile.

Consequence: A developer (or coding agent) reading the conceptual intro and then the tutorial gets two contradictory module shapes with no signal which is current. Agents fail hardest here: they extract Cloudflare.R2Bucket.bind(Bucket) from the intro page, hit a type error, and have no way to know the namespaced form on other pages is the real one. Humans burn time; agents silently generate broken infra code.

The fix: Pick the canonical API surface, regenerate every code block on "What is Alchemy?" and the migration guide's binding section to use it, and add a CI check (the reference is already generated from JSDoc) that lints doc snippets against the actual exports.

2. The `state` property is "required and type-enforced" — except on the pages that omit it (critical)

Location: https://v2.alchemy.run/cloudflare/tutorial/part-1/, https://v2.alchemy.run/what-is-alchemy/, homepage hero, https://v2.alchemy.run/state-store/

Problem: Tutorial Part 1 states flatly: "TypeScript is unhappy: the property is required. Every Stack needs a state store." Yet the homepage hero example and both Stack examples on "What is Alchemy?" pass only with no at all. Meanwhile the State Store page says "By default, state is stored on disk in the directory" — language that implies a default exists and is optional.

Code verification

Runtime snippet checks

Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.

Target history

Prior reports

v2.alchemy.run

Currentpublic
87
2 critical / 2 significant / 3 minor
Jul 10, 202620 pagesv2.alchemy.run
Open

Target history

Prior reports

Loading history.

Check out Manicule.

Alchemy

Alchemy (v2) Documentation Audit

1. Three incompatible API shapes for the same resource across core pages (critical)

2. The `state` property is "required and type-enforced" — except on the pages that omit it (critical)

Runtime snippet checks

Prior reports

Sources

Check out Manicule.

Alchemy

Alchemy (v2) Documentation Audit

1. Three incompatible API shapes for the same resource across core pages (critical)

2. The `state` property is "required and type-enforced" — except on the pages that omit it (critical)

Runtime snippet checks

Prior reports

Prior reports

Sources

3. GitHub README and the production domain document only the incompatible v1 API, with no pointer to v2 (significant)

4. Local state helper has two different names on two different pages (significant)

5. Generated API reference promises input/output tables it doesn't deliver (minor)

6. llms.txt links a docs graph with no llms-full.txt and a 404 sitemap (minor)

7. Install command ships a malformed-looking semver range (minor)

What they do well

Top 3 recommendations

Prior reports

Check out Manicule.

Alchemy

Alchemy (v2) Documentation Audit

1. Three incompatible API shapes for the same resource across core pages (critical)

2. The state property is "required and type-enforced" — except on the pages that omit it (critical)

Runtime snippet checks

Prior reports

Sources

Check out Manicule.

Alchemy

Alchemy (v2) Documentation Audit

1. Three incompatible API shapes for the same resource across core pages (critical)

2. The state property is "required and type-enforced" — except on the pages that omit it (critical)

Runtime snippet checks

Prior reports

Prior reports

Sources

3. GitHub README and the production domain document only the incompatible v1 API, with no pointer to v2 (significant)

4. Local state helper has two different names on two different pages (significant)

5. Generated API reference promises input/output tables it doesn't deliver (minor)

6. llms.txt links a docs graph with no llms-full.txt and a 404 sitemap (minor)

7. Install command ships a malformed-looking semver range (minor)

What they do well

Top 3 recommendations

Prior reports

2. The `state` property is "required and type-enforced" — except on the pages that omit it (critical)

2. The `state` property is "required and type-enforced" — except on the pages that omit it (critical)