Quickstart

Before you start

Requirement	Why it matters
@typespec/compiler 1.10.0	Typra validates emitted behavior against this compiler version.
@typespec/json-schema 1.10.0	JSON AST and verifier metadata depend on the validated schema emitter.
A clear root-object	Generation starts from one fully qualified model.
A deliberate root-namespace	When set, Typra can include additional models from that namespace, not only shapes reachable from the root.
A review baseline	typra-verify compares committed metadata with current output.

Install Typra with the TypeSpec versions it currently validates:

npm install --save-dev @typra/emitter `
  @typespec/compiler@1.10.0 `
  @typespec/json-schema@1.10.0

Add Typra to tspconfig.yaml:

emit:
  - "@typra/emitter"

options:
  "@typra/emitter":
    emitter-output-dir: "{cwd}/generated"
    root-object: "Todo.Contracts.TodoList"
    root-namespace: "Todo.Contracts"
    deterministic-output: true
    emit-targets:
      - type: TypeScript
        output-dir: "generated/typescript"
        test-dir: "generated/typescript/tests"
        import-path: "../index"
      - type: Python
        output-dir: "generated/python"
        test-dir: "generated/python/tests"
        import-path: "todo_contracts"
      - type: Go
        output-dir: "generated/go"
        test-dir: "generated/go/tests"
        import-path: "todo"
        package-name: "todo"
      - type: Java
        output-dir: "generated/java"
        test-dir: "generated/java/tests"
        package-name: "todo.contracts"
      - type: Markdown
        output-dir: "generated/markdown"

Import the emitter library from your TypeSpec entry point:

import "@typra/emitter";

namespace Todo.Contracts;

model TodoList {
  name: string;
  items: TodoItem[];
}

model TodoItem {
  id: string;
  title: string;
  state: TodoState;
}

union TodoState {
  open: "open";
  done: "done";
  archived: "archived";
}

Compile:

npx tsp compile ./path/to/main.tsp --config ./tspconfig.yaml

Typra writes each requested target under its output-dir, writes generated tests when test-dir is set, and writes generated metadata under the configured emitter output root.

Scope note: root-object anchors generation, while root-namespace is the semantic contract root. Typra preserves nested namespaces under that root in generated metadata and structural target folders by default, while namespace, package-name, import-path, and namespace-output: flat control runtime packaging ergonomics. If you need a tighter surface, review emitted metadata and use omit-models deliberately.

For a fuller walkthrough that includes the generated review step, see End-to-end usage.

What success looks like

After compile, the generated root should contain target output plus Typra metadata:

generated\
  typescript\
  python\
  go\
  java\
  markdown\
  json-ast\model.json
  .typra-generated\manifest.json
  .typra-generated\report.json

Verify generated metadata:

npx typra-verify --baseline ./baseline --current ./generated

typra-verify compares committed .typra-generated metadata against current generated metadata. It reports drift in exports, protocols, generated files, package identity, toolchain metadata, protected paths, schema evolution, stale cleanup candidates, hydration seams, and breaking-change classification. It does not delete files.

Recommended CI gate

For committed generated output, set deterministic-output: true, compile with TypeSpec, then run typra-verify against the committed baseline before accepting generated changes.

If verification fails, treat the output as a review signal rather than a formatting problem. Check whether the drift is expected, whether protected paths were touched, and whether the breaking-change classification matches the intended release.