IntersectMBO / IntersectMBO/evolution-sdk
docs: Blueprint codegen has no guide page — workflow, CodegenConfig options, and generated output are undocumented
- Vorherrschende Sprache
- TypeScript
- Sterne
- 22
- Forks
- 30
- Ø Merge
- 5 Std. 29 Min.
- Gemergte PRs (30 T.)
- 12
Beschreibung
## Problem
There is no guide page for the Blueprint module. The only existing documentation is the auto-generated module reference under \`docs/content/docs/modules/blueprint/\`, which lists types and signatures but provides no explanation of the workflow, the codegen pipeline, or config options.
Blueprint codegen is one of the primary entry points for new users: they run Aiken, get a \`plutus.json\`, and need to generate TSchema definitions from it. There is no page explaining how to do this.
### What Needs to Be Written
**What a blueprint is** — The \`plutus.json\` file produced by Aiken. Its structure (preamble, validators, definitions). Why it is the source of truth for on-chain types.
**Parsing a blueprint** — How to load and parse \`plutus.json\` into a \`ParsedBlueprint\` using the SDK. Error cases when the blueprint is malformed.
**Running codegen** — The \`generateFromBlueprint()\` function: inputs, outputs, and where the generated code goes. End-to-end example from \`plutus.json\` to a usable \`TypeScript\` file.
**CodegenConfig in depth** — Each config option explained with before/after generated output:
- \`optionStyle\` — NullOr / UndefinedOr / Union
- \`unionStyle\` — Variant / TaggedStruct
- \`emptyConstructorStyle\` — Literal / Struct
- \`moduleStrategy\` — flat / namespaced with examples of both
- \`forceVariant\` and \`variantFieldNames\` — for overriding unnamed Aiken fields
- \`fieldNaming\` — \`singleFieldName\` and \`multiFieldPattern\`
- \`useSuspend\` — when and why to disable
- \`includeIndex\` — for constructors with non-zero-based indices
**Using generated code** — How to import and use the generated schemas and types in a transaction-building workflow.
**Known limitations and workarounds** — What the codegen cannot automatically infer (see companion issue about Credential/union translation), and how to configure around it today.
### Acceptance Criteria
- [ ] A new guide page (or section) is created — not in \`modules/\`
- [ ] An end-to-end example runs from a real \`plutus.json\` to a usable generated file
- [ ] Every \`CodegenConfig\` option is documented with a before/after code example showing effect on generated output
- [ ] The page explains when codegen is appropriate vs writing TSchema by hand
- [ ] All code examples use \`twoslash\` and compile
Beitragsleitfaden
Rechercherichtung
Start with the auto-generated reference under docs/content/docs/modules/blueprint/ and the generateFromBlueprint() entry point, then inspect ParsedBlueprint and CodegenConfig options. Build the guide around a real plutus.json workflow, including generated TypeScript examples and twoslash checks. Done means the guide covers every listed option, limitations, manual TSchema use, and a compiling end-to-end example.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- typescript
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100