If you’re new to TypeScript and type definitions, start by checking out the TypeScript Handbook . It’s packed with helpful info on how TS works and how to use it properly.

One key thing to keep in mind: type definitions only exist at compile time. They don’t affect your code at runtime, which has some important implications you’ll want to understand early on.

TypeScript definitions  (.d.ts files) let you add static types to existing JavaScript code. They’re only used at compile time for type checking and editor hints, and don’t change how your code runs. Super handy for using JS libraries that don’t ship with TypeScript support.

When working with OneJS/Unity, TypeScript defs are handy because they can be generated from C# types. For example, all .NET/C# namespaces and classes are accessible through the CS. global namespace in JavaScript:

const go = new CS.UnityEngine.GameObject("My Obj");

But because OneJS provides TS typings for many Unity types (and a bit of esbuild magic), we can also use import statements like this:

import { GameObject } from "UnityEngine";
 
const go = new GameObject("My Obj");

Your Own C# Typings

To provide your own TS typings for C# types, you can do something like this:

declare namespace CS {
    namespace MyNamespace {
        class MyClass {
            MyMethod(): void;
            constructor(name: string);
        }
    }
}

This will allow your IDE to understand the type (CS.MyNamespace.MyClass) and provide hints when you use it in your code.

To use the import statement for these C# types, you’ll need to add an ambient module declaration like this:

declare module "MyNamespace" {
    export = CS.MyNamespace
}

Then you can import it like this:

import { MyClass } from "MyNamespace";
 
const myClass = new MyClass("My Obj");

DTS Generator

OneJS comes with a built-in DTS generator that lets you auto-generate TypeScript defs for entire .NET assemblies. It’s basically a wrapper around PuerTS ’s DTS generation, but with extra settings so you can choose exactly which assemblies, namespaces, or classes to include or exclude.

Word of Advice

When working with TypeScript defs for C# types, just remember that auto-generated stuff isn’t always perfect. It usually does an okay job, but things can get messy with generics, nested types, or explicit interfaces. These C# features don’t really map cleanly to TypeScript, so expect to do some manual cleanup.

TS definitions can be super helpful, but they can also turn into a time sink. If you notice you’re spending more time tweaking defs than actually writing code, it’s worth asking if you really need them. The main goal is to make your codebase clearer and easier to maintain, not to chase some ideal of perfect typing. So yeah, use TS defs when they help, but don’t stress too much about making them flawless.