IntersectMBO / IntersectMBO/evolution-sdk

docs: Blueprint codegen has no guide page — workflow, CodegenConfig options, and generated output are undocumented

Open
#155 1 comment 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
TypeScript
Stars
22
Forks
30
Avg merge
5h 29m
Merged PRs (30d)
12

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.