Tsonic GitHub
Edit on GitHub

Getting Started

This guide walks you through installing tsbindgen and generating your first declarations.

Prerequisites

.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

Node.js 18+ (for validation)

node --version  # v18.0.0 or higher

Installation

# Wrapper package (recommended)
npm install tsbindgen

# Or install the scoped package directly
npm install @tsonic/tsbindgen

For using generated declarations, also install the core types package:

npm install @tsonic/core

Verify:

npx tsbindgen --help

From Source

git clone https://github.com/tsoniclang/tsbindgen
cd tsbindgen
dotnet build src/tsbindgen/tsbindgen.csproj

Verify:

dotnet run --project src/tsbindgen/tsbindgen.csproj -- --help

Generating BCL Declarations

Find Your .NET Runtime

dotnet --list-runtimes
# Microsoft.NETCore.App 10.0.0 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

Generate

# Via npm
npx tsbindgen generate -d /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0 -o ./output

# Via dotnet (from source)
dotnet run --project src/tsbindgen/tsbindgen.csproj -- \
  generate -d /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0 -o ./output

This generates declarations for all 130 BCL namespaces.

Understanding the Output

After generation:

output/
+-- System.d.ts                 # Facade (public API)
+-- System.js                   # Runtime stub (throws)
+-- System/
|   +-- bindings.json
|   +-- internal/
|       +-- index.d.ts          # Full declarations
|       +-- metadata.json       # CLR semantics
+-- System.Collections.Generic.d.ts
+-- System.Collections.Generic.js
+-- System.Collections.Generic/
|   +-- bindings.json
|   +-- internal/
|       +-- index.d.ts
|       +-- metadata.json
+-- ... (130 namespaces)

Facade (<Namespace>.d.ts)

The public-facing module consumers import from. Uses curated exports (no export *) to prevent leaking internal $instance/$views types:

// output/System.Collections.Generic.d.ts
import * as Internal from './System.Collections.Generic/internal/index.js';

// Value re-exports for classes (friendly names)
export { List_1 as List } from './System.Collections.Generic/internal/index.js';

// Type aliases for interfaces
export type IEnumerable<T> = Internal.IEnumerable_1<T>;

Internal (<Namespace>/internal/index.d.ts)

Full type declarations:

// output/System.Collections.Generic/internal/index.d.ts
export interface List_1$instance<T> {
    readonly count: int;
    add(item: T): void;
    // ...
}

export declare const List_1: {
    new <T>(): List_1<T>;
};

export type List_1<T> = List_1$instance<T> & __List_1$views<T>;

Generating a Custom Assembly (with Dependencies)

If your assembly references other DLLs outside the runtime directory, add one or more --ref-dir entries so tsbindgen can resolve the full closure.

npx tsbindgen generate -a ./MyLibrary.dll -d $DOTNET_RUNTIME -o ./my-lib-types \
  --ref-dir ./libs

To inspect resolution without generating, use resolve-closure:

npx tsbindgen resolve-closure -a ./MyLibrary.dll --ref-dir $DOTNET_RUNTIME --ref-dir ./libs

Validating Output

Run TypeScript validation:

node test/validate/validate.js --strict

Expected output:

VALIDATION RESULTS
Total errors: 0
✓ STRICT VALIDATION PASSED - Zero TypeScript errors!

Next Steps