Tsonic Compiler Guide

Tsonic compiles a strict, deterministic subset of TypeScript into C#, then hands that generated project to the .NET toolchain for build, publish, test, or pack.

Use this section for

• how the CLI actually works
• how workspaces, projects, and package manifests fit together
• how surfaces differ from packages
• how first-party source packages differ from generated CLR binding packages
• how generated output is structured
• what the current architecture guarantees and rejects

Current model

The current V1 model is:

• one compiler-owned noLib baseline
• one active ambient surface per workspace
• explicit package-based CLR and module interop
• deterministic lowering only; unsupported dynamic cases are rejected
• source-package graphs compiled as part of the same Tsonic program

Read in this order

• Getting Started
• CLI Workflow
• Surfaces and Packages
• Workspace and Project Files
• Build Modes
• Build Output
• Bindings
• CLR Bindings and Interop
• Type System Rules
• Diagnostics
• Testing and Quality Bar
• Examples
• Architecture Section

Practical rule of thumb

• use clr when you want a CLR-first ambient world
• use @tsonic/js when you want a JS ambient world
• add @tsonic/nodejs when you want Node-style modules
• add generated binding packages when you need CLR libraries beyond the baseline

What this guide does not do

This section is not a copy of repo-internal design notes. It explains the current public model for users and downstream application authors.