ts-for-gir

ts-for-gir is the TypeScript type-definition generator that powers IDE autocomplete + type-checking for every gjsify project (and many non-gjsify GJS projects). It reads GObject Introspection (.gir XML) files and emits .d.ts declarations covering GLib, GIO, GTK, GStreamer, libadwaita, WebKit, and ~700 other GNOME-stack modules.

What you get

Compile-time type safety for every import Gtk from 'gi://Gtk?version=4.0'.
IDE jump-to-definition into @girs/* declarations: hover a Gtk.Button to see its constructor, methods, signals.
Pre-generated npm packages at gjsify/types — npm i @girs/gtk-4.0 instead of running the generator yourself.
First-class gjsify integration: the types-gjsify starter template wires ts-for-gir generate into gjsify install, gjsify build, and gjsify run so a fresh project compiles in seconds.

Install

Five paths — pick whichever matches your toolchain.

GJS — no Node.js required _experimental

Three equivalent Node-free options, depending on whether you want a one-shot run, a managed install, or a self-updating standalone install. All require only GJS at runtime.

One-shot — gjsify dlx (npx-style, no install):

gjsify dlx @ts-for-gir/cli list
gjsify dlx @ts-for-gir/cli generate Gtk-4.0

gjsify dlx fetches the package into a content-addressed cache (~/.cache/gjsify/dlx), runs its GJS bundle, and reuses the cache on subsequent invocations of the same spec. Pair with --reinstall to force a refresh.

Global install via the gjsify CLI:

gjsify install -g @ts-for-gir/cli
ts-for-gir --help

Installs into the user-global XDG location (~/.local/share/gjsify/global) and symlinks the binary to ~/.local/bin/ts-for-gir. Re-run the same command to update.

Bootstrap installer — curl | gjs one-liner (handy when the gjsify CLI is not yet installed):

curl -fsSL https://raw.githubusercontent.com/gjsify/ts-for-gir/main/install.js -o /tmp/install.js
gjs -m /tmp/install.js && rm /tmp/install.js

Installs to ~/.local/bin/. Update later with ts-for-gir self-update.

Node.js

npx @ts-for-gir/cli --help
# or globally:
npm install -g @ts-for-gir/cli

Quick start

Scaffold a new project — pick a template interactively, or pass --template <id>:

gjsify dlx @ts-for-gir/cli create my-app
# or via npm
npx @ts-for-gir/cli create my-app

Template	Best for
`types-gjsify`	Node-free GJS app — all dev scripts (install, build, run, format) routed through gjsify
`types-npm`	Single-package, types from `@girs/*` npm, esbuild + node
`types-locally`	Generate types into `./@types/` (no `@girs/*` dep)
`types-workspace`	npm workspace with `@girs/*` as locally-generated workspace packages

Run it:

cd my-app
gjsify run start    # types-gjsify template
# or
npm start           # any other template

Generating types yourself

If the pre-generated @girs/* packages don’t fit (custom GIR files, project-local types, an experimental gnome-shell version, …) — generate locally:

ts-for-gir generate Gtk-4.0                  # one module
ts-for-gir generate '*'                      # everything available on the system
ts-for-gir generate Gtk-4.0 --reporter       # with diagnostics
ts-for-gir analyze -f ./ts-for-gir-report.json
ts-for-gir --help                            # full surface

The --reporter flag emits a JSON file summarising every unresolved type, version conflict, and skipped construct — ts-for-gir analyze -f <report> then turns that into a per-namespace severity table.

Pre-generated `@girs/*` packages

If you just want types without running the generator:

npm install @girs/gjs @girs/gtk-4.0

import '@girs/gjs';
import '@girs/gjs/dom';
import '@girs/gtk-4.0';

import Gtk from 'gi://Gtk?version=4.0';

const button = new Gtk.Button();

All ~700 packages are listed at github.com/gjsify/types. Missing a module? Open an issue.

Patterns reference

The Patterns section of this site documents the idioms that ship with the generated types:

GObject classes — GObject.registerClass() forms, the static-block pattern, init-order rules behind GNOME/gjs#704, and the static override $gtype: GObject.GType<Foo> declaration that narrows the statically-inherited $gtype from the base class.
Bridge widgets — how Canvas2DBridge / WebGLBridge / IFrameBridge / VideoBridge pair a polyfill DOM element with a real GTK widget so browser-shaped code drives the GTK surface directly.

Project structure

Package	Responsibility
`@ts-for-gir/cli`	Command-line interface — generate, analyze, create, doc, self-update
`@gi.ts/parser`	Parser for GObject Introspection XML files
`@ts-for-gir/lib`	Core library for processing GIR data
`@ts-for-gir/generator-typescript`	TypeScript definition generator
`@ts-for-gir/generator-html-doc`	HTML documentation generator (TypeDoc)
`@ts-for-gir/generator-json`	JSON representation for analysis + tooling
`@ts-for-gir/generator-base`	Shared base class for generators
`@ts-for-gir/typedoc-theme`	Custom TypeDoc theme inspired by gi-docgen
`@ts-for-gir/gir-module-metadata`	Curated metadata (descriptions, logos, licenses) for GIR namespaces
`@ts-for-gir/templates`	EJS templates for generated packages
`@ts-for-gir/reporter`	Reporting system for problems and statistics
`@ts-for-gir/language-server`	Language server for GIR files (experimental)

Showcase

GNOME applications shipping with ts-for-gir-generated types:

Audio Player · Counters · Ignition
Learn 6502 · Sound Recorder · Sticky Notes
Weather · K’uychi

GNOME Shell Extensions: gTile, Copyous, Rounded Window Corners.