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

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

documentation enhancement

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from IntersectMBO/evolution-sdk

All issues in IntersectMBO/evolution-sdk

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.