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 project init

The easiest way to start:

mkdir my-app
cd my-app
tsonic project init

This creates:

my-app/
├── src/
│   └── App.ts           # Entry point
├── tsonic.json          # Configuration
├── package.json         # NPM package with scripts
├── .gitignore           # Ignores generated/ and out/
└── README.md            # Project readme

Project Init Options

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

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

Manual Setup

If you prefer manual setup:

  1. Create tsonic.json:
{
  "rootNamespace": "MyApp",
  "entryPoint": "src/App.ts",
  "sourceRoot": "src"
}
  1. Create src/App.ts:
import { Console } from "@tsonic/dotnet/System.js";

export function main(): void {
  Console.writeLine("Hello!");
}
  1. Install type packages:
npm install --save-dev tsonic @tsonic/core @tsonic/globals

Building and Running

Build Command

Generate C# and compile to native:

tsonic build src/App.ts

Output goes to out/app (or out/app.exe on Windows).

Run Command

Build and execute in one step:

tsonic run src/App.ts

NPM Scripts

The generated package.json includes convenience scripts:

npm run build    # tsonic build src/App.ts
npm run dev      # tsonic run src/App.ts

Understanding the Output

After building:

my-app/
├── generated/           # Generated C# code
│   ├── src/
│   │   └── App.cs       # Your code as C#
│   ├── Program.cs       # Entry point wrapper
│   └── tsonic.csproj    # .NET project file
└── out/
    └── 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