Skip to content

Add a designed, CI-verified sdk-js cookbook (69 recipes) + agent on-ramp#1199

Open
lamentierschweinchen wants to merge 16 commits into
multiversx:developmentfrom
lamentierschweinchen:cookbook-design-layer
Open

Add a designed, CI-verified sdk-js cookbook (69 recipes) + agent on-ramp#1199
lamentierschweinchen wants to merge 16 commits into
multiversx:developmentfrom
lamentierschweinchen:cookbook-design-layer

Conversation

@lamentierschweinchen

@lamentierschweinchen lamentierschweinchen commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

What this is

A structured, browsable replacement for docs/sdk-and-tools/sdk-js/sdk-js-cookbook-v15.md (the ~128 KB single-file cookbook): 69 atomic, copy-paste recipes across 13 sections, each solving one concrete task and showing every file it needs. It covers sdk-core, sdk-dapp v5, and the sdk-rs contract framework where that is the right tool.

Three things make it more than a reorganization:

  1. Every recipe's code is CI-verified. A new TypeScript verification harness extracts the code fences from each page and runs tsc --noEmit --strict over them. The teal Verified badge on a recipe means that check passed on the date shown. What a reader copies is what compiles.
  2. It is designed. A small set of React components renders a per-recipe meta strip (difficulty, estimated time, verified badge, SDK versions) and a browsable card index, styled on the MultiversX design tokens.
  3. It has an agent on-ramp. A "Agent or agentic engineer? Start here" page routes human developers to recipes and coding agents to the machine-readable surface (llms.txt / llms-full.txt), which now includes every recipe.

Why

The current sdk-js-cookbook-v15.md is a single 128 KB file. This restructures the same intent into a per-recipe, navigable, verifiable cookbook. It is a strict superset: a coverage diff against the existing v15 (and v14 where still relevant) confirmed that every topic it covers is present here, and gaps were filled before this PR. Nothing the current cookbook has is dropped.

The CI harness (mirrors your existing Rust tutorial CI)

The repo already verifies tutorial code for Rust: testing/extract-tutorial-code extracts fenced code from the crowdfunding tutorial and runs cargo test (testing/rust-tutorial-ci.sh, .github/workflows/rust-tutorial-ci.yml). There was no equivalent for JS/TS, so the sdk-js cookbook's code was untested.

This PR adds the TS mirror of that exact pattern:

Existing (Rust) Added (TypeScript)
testing/extract-tutorial-code/ testing/cookbook-ts/
testing/rust-tutorial-ci.sh testing/cookbook-ts-ci.sh
.github/workflows/rust-tutorial-ci.yml .github/workflows/cookbook-ts-ci.yml
cargo run → cargo test npm run extract → tsc --noEmit --strict

Only titled fences (```ts title="src/foo.ts") are extracted and type-checked; untitled fences and bash/text blocks are illustrative. testing/cookbook-ts/CONVENTION.md documents the authoring rule ("what is shown is what is compiled").

Footprint (deliberately small)

  • src/components/cookbook/ — a handful of plain React + CSS-module components (RecipeCard, the meta chips, the verified badge, the index grid).
  • src/theme/DocItem/Content/index.js — one guarded swizzle that renders the meta strip only on cookbook pages (frontmatter-gated); all other docs are untouched.
  • src/css/cookbook.css — a scoped Infima reskin on the MultiversX tokens; no global chrome is changed.
  • scripts/generate-cookbook-manifest.js — build-time index manifest from recipe frontmatter.
  • scripts/generate-llms-txt.js — extended (not forked) so recipes appear in llms.txt / llms-full.txt.

Verification

  • testing/cookbook-ts-ci.sh (npm ci → extract → tsc --noEmit --strict): green.
  • docusaurus build: green; zero broken links originate from or point into the cookbook.
  • codespell (your .codespell config): clean.
  • markdownlint (your .markdownlint.jsonc): clean except one MD033/no-inline-html on the index page's <CookbookIndex> grid component (intrinsic to rendering the card grid; markdownlint is not a CI gate here and does not scan .mdx by default).

Decisions for the maintainer

  1. Replaces sdk-js-cookbook-v15.md. This PR removes the v15 monolith and adds a client redirect from its URL (/sdk-and-tools/sdk-js/sdk-js-cookbook) to the new cookbook index, and repoints the five in-repo links that pointed into it (the three anchored ones now target the specific new recipes). Coverage was diffed first, so nothing the old cookbook covered is lost. The v14 legacy file is untouched. If you would rather keep v15 around for a deprecation window, that is a one-line revert.
  2. The TS CI workflow. New for JS/TS docs. It mirrors your Rust one and keeps the cookbook honest, but it is a workflow your team would own. If you would rather not add JS CI, the recipes still stand as designed pages.
  3. One superset tsconfig compiles all recipes together (a small strictness relaxation for maintainability); per-recipe configs are the alternative.
  4. MD033 on the index (the <CookbookIndex> grid) — kept, since suppressing it via an HTML comment would break MDX parsing.
  5. Agent stack references are conservative: the on-ramp links the existing learn/ai-agents page and the served llms.txt, and does not feature emerging/devnet-preview items to avoid overclaiming on a docs surface.

Credit

Recipes were authored and verified against the live network and the installed SDKs (sdk-core 15.4.1, sdk-dapp v5). Verification surfaced a handful of real SDK issues along the way, which are being reported to the sdk-js team separately.

popenta and others added 16 commits July 6, 2026 13:46
@popenta
Merge pull request multiversx#1189 from multiversx/development
0db7a4e 
Development to main
@popenta
Merge pull request multiversx#1196 from multiversx/development
2fbd032 
Merge development into main
@stefangutica
Merge pull request multiversx#1198 from multiversx/development
0fa8ec0 
Development -> Main
@lamentierschweinchen
cookbook design layer: components + swizzle + scoped CSS + llms exten…
6170455 
…sion
@lamentierschweinchen @claude
cookbook: TS verification CI mirroring the Rust tutorial CI + 3 exemp…
f9792b6 
…lar recipes

Add a TypeScript verification harness for the sdk-js cookbook, mirroring the
repo's Rust tutorial CI (testing/rust-tutorial-ci.sh + extract-tutorial-code):

- testing/cookbook-ts/: a fence extractor (parser.ts + extract.ts) that pulls
  titled ts/tsx fences from cookbook recipe MDX into a strict TS project, plus
  CONVENTION.md documenting the authoring convention.
- testing/cookbook-ts-ci.sh + .github/workflows/cookbook-ts-ci.yml: extract then
  tsc --noEmit --strict, the "what is shown is what is compiled" gate.
- Three exemplar recipes ported to docs/sdk-and-tools/sdk-js/cookbook/, carrying
  the meta-strip frontmatter the Track A swizzle reads: a read-side
  network-providers recipe, a write-side transactions recipe, and a dApp/React
  sdk-dapp recipe.
- sidebars.js: a "Cookbook (recipes)" category.

Verified: extractor assembles 10 files across 3 recipes; tsc --noEmit --strict
passes; a deliberate type error is rejected (TS2322); Docusaurus build is green
with the meta strip server-rendered; markdownlint + codespell pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: port start-here, migration, and wallets recipes (wave 1)
fb51ec1 
Port 14 recipes onto the proven TS-verification harness + design layer:

- start-here (5): vite-react-minimal, nextjs-minimal, local-https-setup,
  sign-and-send, v4-to-v5-migration
- migration (3): dapp-provider-to-initapp, get-account-info-v4-vs-v5,
  send-transactions-to-transaction-manager
- wallets (6): wallet-login-button, defi-extension-login, walletconnect-login,
  ledger-login, native-auth, typescript-strict-mode-checklist

Each page inlines its source verbatim as titled ts/tsx fences (v4 "before"
and next/vite config files shown as untitled illustrative fences since they
can't compile against the harness deps). Internal-only doc references scrubbed
from comments. Sidebar wired under "Cookbook (recipes)".

Verified: cookbook-ts extract + tsc --noEmit --strict green (57 files / 16
recipes incl. exemplars); docusaurus build green, all pages generate, no new
broken links; markdownlint + codespell clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen
cookbook: normalize last_validated to CI-verify date (uniform badges)
388ad1b
@lamentierschweinchen @claude
cookbook: port accounts and signing recipes (wave 2)
ab6a9d4 
Port the entire prototype `accounts` section (14 recipes) onto the proven
TS-verification template, under docs/.../cookbook/accounts/:

- Key management: generate-mnemonic-derive-keys, account-from-keys,
  keystore-save-load, pem-save-load
- Addresses & state: address-utilities, fetch-account-state, manage-nonces
- Signing: sign-verify-message, sign-verify-transaction,
  hash-signing-transaction
- Guardians & relayed: set-guardian, guard-unguard-account,
  apply-guardian-to-transaction, relayed-v3-transaction

Each page carries the meta-strip frontmatter (difficulty + sdk_versions),
last_validated normalized to 2026-07-16, Docusaurus admonitions in place of
Starlight <Aside>, and every compile-required source file inlined verbatim as
a titled ts fence. Internal-only references (CLAUDE.md, authoring-process
notes) scrubbed from prose and comments; cross-links to unported pages
reworded to avoid new broken links. Added an "Accounts and signing" category
to sidebars.js under Cookbook (recipes).

Verified: `npm run extract` + `tsc --noEmit --strict` green across all 30
recipes (74 files); markdownlint (0 errors) and codespell clean on the 14 new
pages; `docusaurus build` succeeds with all pages generated and no new broken
links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: port tokens, transactions, and governance recipes (wave 3)
2e3f8ae 
Port 13 recipes onto the verified Docusaurus cookbook template:
- tokens (8): issue fungible/NFT/SFT, set special roles, local mint/burn,
  lifecycle (freeze/pause/wipe), fetch metadata, fetch balances
- transactions (3): send-esdt, multi-token-transfer, track-transaction-status
- governance (2): create-proposal, vote-close-proposal

Frontmatter meta strip (difficulty + sdk_versions), admonitions, and titled
code fences match waves 1-2. Public-valuable SDK-bug pitfalls kept (unset-role
wrong-flag, pause/freeze/wipe wrong-receiver, LocaMinting typo); internal-only
references scrubbed. Adds Tokens and Governance sidebar categories and appends
the new transactions.

tsc --noEmit --strict green across all cookbook recipes; Docusaurus build green
with no new broken links; markdownlint and codespell clean on the new pages.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: port network-providers, delegation, and multisig recipes (w…
e8c1107 
…ave 4)

Port 14 recipes onto the verified TS cookbook template:
- network-providers (6): fetch-network-config-status, fetch-a-block,
  await-account-on-condition, await-transaction-on-condition,
  simulate-estimate-transaction, custom-api-request
- delegation (5): create-delegation-contract, delegate-stake,
  claim-and-redelegate-rewards, undelegate-and-withdraw,
  query-delegation-contract
- multisig (3): propose-action, sign-perform-action, read-multisig-state

Add Delegation and Multisig sidebar categories and append the six
network-providers pages to the existing category. Extract + strict tsc,
markdownlint, codespell, and the Docusaurus build all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: port smart-contract call, deploy, and Rust authoring recipe…
c499b34 
…s (wave 5)

Final port wave. Adds 11 recipes across three new "Cookbook (recipes)"
categories:

Smart contracts (call & query): load-abi, query-contract-view,
call-contract-endpoint, call-payable-endpoint, decode-return-data,
decode-contract-events.

Smart contracts (deploy & upgrade): compute-contract-address,
deploy-contract, upgrade-contract.

Smart contracts (Rust authoring): new-contract-from-template,
storage-mapper-decision-table.

The ABI-loading TS recipes take an Abi-typed parameter (subject files) or
read the ABI JSON at runtime via fs (load-abi's index.ts), so every titled
ts fence type-checks under the harness with no bare JSON import. The Rust
authoring recipes ship illustrative rust fences (not extracted/compiled).

Verified: extract + tsc --noEmit --strict green across all 66 recipes;
docusaurus build green with no new broken links; markdownlint and codespell
clean on the 11 new pages.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: front door, agent on-ramp, and machine-surface assembly (pa…
596c478 
…ss A)

Build the cookbook's browsable entry points on top of the 69 ported recipes
and retire the Track-A demo pages.

- Landing page (docs/.../cookbook/index.mdx, slug = cookbook root) renders all
  69 recipes grouped by the 13 sections via the Track-A RecipeGrid/RecipeCard
  components. Cards are driven by a build-time manifest
  (scripts/generate-cookbook-manifest.js -> src/data/cookbook-manifest.json)
  that reads each recipe's real frontmatter and mirrors the curated sidebar
  order, so no list is hand-maintained. New CookbookIndex component adds a
  manifest-driven jump-nav with per-section counts.
- Agent on-ramp (docs/.../cookbook/agents.mdx) routes human devs to the recipes
  and coding agents to the machine-readable surface (llms.txt / llms-full.txt)
  and the existing learn/ai-agents page (mx-ai-skills). Placed first in the
  cookbook sidebar.
- Retire cookbook-preview.mdx + cookbook-preview-recipe.mdx and their sidebar
  entries; make the index the "Cookbook (recipes)" category link.
- Regenerate static/llms.txt + llms-full.txt: all 69 recipes now appear as
  tagged lines / full content. Wire the manifest generator into prebuild.

Build green; TS harness (extract + tsc --strict) green; codespell clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
cookbook: restore cross-link graph and surgical em-dashes (assembly p…
7122c54 
…ass B)

All 69 recipes now exist, so the inter-recipe cross-links the porting waves
dropped (to avoid links to then-unported pages) can be real again. Restore
them from the prototype's see_also curation, and lightly restore em-dashes
where a wave's comma/colon substitution left a run-on.

Cross-links (18 see_also edges across 12 recipes):
- Convert 9 plain-texted "covered in the X recipes" See also bullets back into
  real recipe links (address-utilities, create-delegation-contract,
  create-proposal, fetch-account-state, issue-nft-collection, propose-action,
  query-delegation-contract, vote-close-proposal, manage-nonces).
- Restore the prototype's curated See also set on 3 recipes the waves had
  filled with placeholder links (configure-network-provider,
  read-connected-account, send-egld).
- All targets are real ported pages under
  /sdk-and-tools/sdk-js/cookbook/<section>/<slug>. No fabricated links.
  wallet-login-button left as-is: its rendered base-setup link (vite-react-minimal)
  is correct; the stale frontmatter see_also (nextjs-minimal) was never rendered.

Em-dashes (6 surgical restorations, 5 recipes): manage-nonces (x2),
await-account-on-condition, await-transaction-on-condition, native-auth,
simulate-estimate-transaction, only where a comma splice or emphatic appositive
read as a run-on. No code fences touched.

Additive, prose-only. Verified green: extract + tsc --noEmit --strict via
testing/cookbook-ts-ci.sh; Docusaurus build (zero cookbook broken links);
markdownlint-cli2 (only the known index.mdx MD033/CookbookIndex); codespell clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen @claude
docs(cookbook): warm the recipe prose, cut self-narrating AI tells
216d176 
Surgical copy pass across the sdk-js cookbook recipe pages. Removes the self-narrating "this recipe shows/demonstrates/walks" frame, throat-clearing ("worth noting", "it is tempting to", "the point is"), and cutesy filler ("out of the box", "under the hood") in favour of plain, direct wording matching the already-rewritten index/agents front door.

Prose only: no code fences, links, admonitions, or technical claims changed. 17 recipe pages edited; the rest left as-is. Front-door index/agents rewrites (already done) are included in this commit.

Verified: docusaurus build green (no new broken links); cookbook-ts extract + tsc --noEmit --strict green; markdownlint + codespell clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen
cookbook: correctness-review prose fixes (theme/version/https/mkcert …
ef9fe94 
…precision) + drop redundant await
@lamentierschweinchen
cookbook: replace sdk-js-cookbook-v15 with the new cookbook (redirect…
a3b2e81 
… + repoint inbound links)
@lamentierschweinchen
lamentierschweinchen marked this pull request as ready for review July 16, 2026 12:13
@popenta
popenta changed the base branch from main to development July 16, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@lamentierschweinchen @popenta @stefangutica