Sorbet::Typescript

Sorbet::Typescript exports Sorbet T::Enum and T::Struct definitions into JSON metadata and TypeScript declarations so front-end clients can stay in sync with your Ruby types.

DocSpring built this gem for LogStruct to keep its documented payload types in lockstep with the Ruby source. The generated metadata powers the live reference at logstruct.com/docs/sorbet-types and all sample logs published across logstruct.com, ensuring every example stays current through code generation.

See how LogStruct wires the exporter into its build pipeline in scripts/generate_structs.rb.

Add the gem to your application:

bundle add sorbet-typescript

If you need the latest unreleased changes, point bundler at GitHub:

bundle add sorbet-typescript --git https://github.com/DocSpring/sorbet-typescript

The executable sorbet-typescript inspects the namespaces you specify and writes JSON and/or TypeScript files:

bundle exec sorbet-typescript export \
  --struct-namespace MyApp::Types \
  --enum-namespace MyApp::Enums \
  --typescript-file app/frontend/types/generated.ts

You can also drive the export with a YAML config (default path sorbet_typescript.yml):

requires:
  - config/environment
struct_namespaces:
  - MyApp::Types
enum_namespaces:
  - MyApp::Enums
outputs:
  typescript_file: app/frontend/types/generated.ts
  enums_json: tmp/sorbet/enums.json
  structs_json: tmp/sorbet/structs.json

Run it with bundle exec sorbet-typescript export --config sorbet_typescript.yml. Any CLI options override the config file.

Each output captures the same Sorbet definitions in a format that is convenient for different consumers:

• Enums JSON (enums_json) – map of fully qualified enum names to metadata with the original name, the simple (namespace-free) name, and an ordered list of values (name, serialized).
• Structs JSON (structs_json) – map of fully qualified struct names to field metadata. Every field entry describes its Sorbet type (type, enum_name, struct_name, etc.), optionality, and—when the Sorbet definition provides defaults—the serialized enum default (default_enum_* keys) or literal default (default).
• TypeScript file (typescript_file) – ambient definitions that mirror the Sorbet types: literal unions for enums and interfaces for structs. Enum-backed fields become unions of the serialized values so the TS compiler enforces the same constraints as Sorbet.

These files share the same structure whether you call the CLI or the Ruby API, making it easy to feed the JSON into documentation generators, schemas, or client SDKs.

If you want to script the export yourself, use the Exporter directly:

exporter = Sorbet::Typescript::Exporter.new(
  enum_namespaces: ["MyApp::Enums"],
  struct_namespaces: ["MyApp::Types"]
)

exporter.export(
  typescript_file: "app/frontend/types/generated.ts",
  enums_json: "tmp/sorbet/enums.json",
  structs_json: "tmp/sorbet/structs.json"
)

The returned ExportData object contains enums and structs hashes that you can leverage for custom tooling.

After cloning the repo, install dependencies and run the task workflow:

task setup
task all

Useful individual commands:

• task typecheck – run Sorbet (srb tc) with the strict sigils enforced in the repo
• task lint / task lint:fix – Standard/RuboCop lint checks and auto-corrections
• task test – execute the Minitest suite via scripts/test.rb

Make sure you have Go Task installed to run the task command.

Bump the version in lib/sorbet/typescript/version.rb, then run:

bundle exec rake release

This creates a git tag, pushes the commit and tag, and publishes the gem.

The gem is available as open source under the terms of the MIT License.