docs: Blueprint codegen has no guide page — workflow, CodegenConfig options, and generated output are undocumented
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- typescript
- Domain
- documentation
Research direction
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.
Written by the indexing model from the issue text.
Description
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
- Dominant language
- TypeScript
- Stars
- 22
- Forks
- 30
- Avg merge
- 13h
- Merged PRs (30d)
- 14
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from IntersectMBO/evolution-sdk
-
dependencies good first issue
Difficulty 1/5 Under an hour Newbie friendliness 93/100
IntersectMBO/evolution-sdk#541 ·
-
bug external-review
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
IntersectMBO/evolution-sdk#530 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
IntersectMBO/evolution-sdk#518 ·
-
enhancement external-review
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
IntersectMBO/evolution-sdk#456 · 1 comment ·
-
bug external-review
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
IntersectMBO/evolution-sdk#398 ·
All issues in IntersectMBO/evolution-sdk
Similar issues
-
bot:ai-assisted component:compact-js status:untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
midnightntwrk/midnight-sdk#403 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
joinmarket-webui/jam#1496 · 1 comment ·
-
Tech
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
opencrvs/opencrvs-core#13865 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
linagora/twake-calendar-frontend#1377 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
EclipseFdn/open-vsx.org#13385 · 1 comment ·