Tsonic User Guide
Tsonic compiles TypeScript to native executables via C# and .NET NativeAOT.
Table of Contents
Getting Started
- Getting Started - Installation and first project
- CLI Reference - Commands and options
- Configuration - tsonic.json reference
Language
- Language Guide - Supported features
- Type System - Type mappings
- Numeric Types - Integer types and narrowing
- Generators - Sync, async, and bidirectional generators
- Callbacks - Action and Func patterns
- Async Patterns - Async/await and for-await
- .NET Interop - Using .NET BCL
- CLR Bindings & Workspaces - Where bindings live; multi-project repos
- Language Intrinsics - stackalloc, trycast, thisarg, etc.
- JavaScript Runtime - Optional JS-style APIs via
@tsonic/js
Build
- Build Output - Pipeline and output
- Diagnostics - Error codes reference
Reference
- Examples - Code examples
- Troubleshooting - Common issues
- Limitations - What Tsonic can’t do (yet)
Quick Links
- Architecture Documentation - For contributors and advanced users
- GitHub Repository
- npm Package
Overview
What is Tsonic?
Tsonic is a compiler that transforms TypeScript source code into native executables:
TypeScript → IR → C# → NativeAOT → Native Binary
Why Tsonic?
- Native Performance: Compile to fast, single-file executables
- TypeScript Familiarity: Use the language you know
- Full .NET Access: Call any .NET library
- No Runtime Required: Self-contained binaries
Direct .NET Access
- C# semantics for all types
- Import from System.*, System.IO, System.Linq, etc.
- Full BCL access
- Native arrays (
T[]) and .NET collections
Prerequisites
- Node.js 22+: For the CLI and type packages
- .NET 10 SDK: For compilation
- npm: For package management
Verify installation:
node --version # v22.0.0 or higher
dotnet --version # 10.0.x
Installation
npm install -g tsonic
tsonic --version
Your First Program
# Create project
mkdir hello && cd hello
tsonic project init
# Build
npm run build
# Run
./out/app
Output:
Hello from Tsonic!
Doubled: 2, 4, 6, 8, 10