Tsonic GitHub
Edit on GitHub

Getting Started

This guide walks you through installing Tsonic and building your first program.

Prerequisites

Node.js 22+

Download from nodejs.org or use a version manager:

# Using nvm
nvm install 22
nvm use 22

# Verify
node --version

.NET 10 SDK

Download from dotnet.microsoft.com:

# Linux (Ubuntu/Debian)
sudo apt-get install dotnet-sdk-10.0

# macOS
brew install dotnet-sdk

# Verify
dotnet --version

macOS: Xcode Command Line Tools

Required for NativeAOT builds on macOS:

xcode-select --install

# Verify
xcrun --show-sdk-path

Installation

npm install -g tsonic

Verify:

tsonic --version

Local Installation

For project-specific usage:

npm install --save-dev tsonic
npx tsonic --version

Creating a Project

Using tsonic init

The easiest way to start:

mkdir my-app
cd my-app
tsonic init

This creates:

my-app/
├── tsonic.workspace.json     # Workspace config (dependencies live here)
├── libs/                     # Workspace-scoped DLLs
├── packages/
│   └── my-app/
│       ├── tsonic.json       # Project config
│       ├── package.json      # Project package.json (minimal)
│       └── src/App.ts        # Entry point
├── package.json              # Workspace package.json (npm workspaces + scripts)
└── .gitignore                # Ignores generated/, out/, node_modules/, .tsonic/

Init Options

# Skip installing type packages
tsonic init --skip-types

# Specify type package version
tsonic init --types-version <ver>

Adding JS / Node.js APIs

Install optional libraries via npm bindings packages:

tsonic add npm @tsonic/js
tsonic add npm @tsonic/nodejs

Building and Running

Build Command

Generate C# and compile to native:

tsonic build

Output goes to packages/<project>/out/<app> (or .exe on Windows).

If your workspace has multiple projects, select one explicitly:

tsonic build --project my-app

Run Command

Build and execute in one step:

tsonic run

NPM Scripts

The generated package.json includes convenience scripts:

npm run build    # tsonic build
npm run dev      # tsonic run

Understanding the Output

After building:

my-app/
└── packages/
    └── my-app/
        ├── generated/           # Generated C# code
        │   ├── src/
        │   │   └── App.cs       # Your code as C#
        │   ├── Program.cs       # Entry point wrapper
        │   └── tsonic.csproj    # .NET project file
        └── out/
            └── my-app           # Native executable

Generated C# (Example)

Your TypeScript:

import { Console } from "@tsonic/dotnet/System.js";

export function main(): void {
  Console.WriteLine("Hello!");
}

Becomes:

namespace MyApp
{
    public static class App
    {
        public static void main()
        {
            global::System.Console.WriteLine("Hello!");
        }
    }
}

Next Steps

Specialized Guides