Architecture

This page summarizes the Tsonic architecture.

Compiler model

Tsonic compiles a deterministic TypeScript subset into generated C# and then uses the .NET toolchain for managed or NativeAOT outputs.

The compiler model is:

compiler-owned noLib language prelude
exactly one ambient surface per workspace
explicit package-based CLR and module interop
source-package manifests for authored TypeScript packages
generated binding metadata for CLR packages
hard diagnostics for unsupported or unprovable constructs

Ambient surfaces

The workspace surface chooses the ambient world:

clr is the default CLR-first surface.
@tsonic/js is the JavaScript ambient surface.

@tsonic/nodejs and @tsonic/express are packages layered onto the JS surface; they are not separate surfaces.

Package families

Compiler and core packages

tsonic — compiler and CLI
@tsonic/core — primitive intent types and compiler intrinsics
@tsonic/globals — shared ambient declarations used by surface packages

First-party TypeScript source packages

@tsonic/js
@tsonic/nodejs
@tsonic/express

These packages are authored in TypeScript and described by tsonic.package.json.

Generated CLR binding packages

@tsonic/dotnet
@tsonic/aspnetcore
@tsonic/microsoft-extensions
@tsonic/efcore
@tsonic/efcore-sqlite
@tsonic/efcore-sqlserver
@tsonic/efcore-npgsql

These packages are generated by tsbindgen and contain .d.ts facades plus bindings.json compiler metadata.

Workspace model

The root tsonic.workspace.json owns shared workspace configuration:

surface
target framework
CLR framework references
CLR NuGet package references
type roots
local DLL references

Each package under packages/<name> owns its project configuration in tsonic.json and, when published or imported as source, its tsonic.package.json source-package manifest.

Release quality model

Release readiness is ecosystem-level:

compiler gate in tsonic
package selftests in first-party source packages
generator tests in tsbindgen
generated binding package validation
downstream verification across real applications

The publish wave is treated as one coherent ship decision.