TypeScript type definition generator for GObject introspection GIR files

ts-for-gir generates accurate TypeScript definitions from GObject Introspection for GJS projects — strong typing, IDE jump-to-definition, autocompletion across the whole GNOME stack.

📖 Project page on the gjsify website: gjsify.github.io/gjsify/projects/ts-for-gir — install paths, quickstart, generator usage, links to the related Patterns docs.

Browse the full TypeScript API Documentation for GLib, GTK, GStreamer, and more.

gjsify dlx @ts-for-gir/cli create my-app   # no install, no Node.js
# or
npx @ts-for-gir/cli create my-app          # via npm

Pick a template interactively, or pass --template <id>:

cd my-app && npm start    # or `gjsify run start` for types-gjsify

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. Powered by GJSify.

Alternative — if you already have the gjsify CLI installed: gjsify dlx @ts-for-gir/cli <args> (npx-style, no install) or gjsify install -g @ts-for-gir/cli (managed global).

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

ts-for-gir generate Gtk-4.0                          # generate types for a single module
ts-for-gir generate Gtk-4.0 --reporter               # with diagnostics
ts-for-gir analyze -f ./ts-for-gir-report.json       # inspect the report
ts-for-gir --help                                    # all commands

See the CLI documentation for advanced options.

If you just want the types without generating them yourself:

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 packages are listed at gjsify/types. Missing a module? Open an issue.

GNOME Applications

• Audio Player — Play audio files
• Counters — Keep track of anything
• Ignition — Manage startup apps and scripts
• Learn 6502 — Learn programming on vintage game consoles
• Sound Recorder — A simple, modern sound recorder
• Sticky Notes — Pin notes to your desktop
• Weather — Show weather conditions and forecast
• K'uychi — Generate color palettes

GNOME Shell Extensions

• gTile — Tiling window management for GNOME Shell
• Copyous — Clipboard manager for GNOME Shell
• Rounded Window Corners — Add rounded corners to windows

Looking for a starting point? These example projects demonstrate how to use the TypeScript definitions with various bundlers:

• GTK 4 Template with Vite — Modern UI with Vite bundling
• GNOME TypeScript Template — A template using GTK, libadwaita, TypeScript, Flatpak, and Meson

More examples with screenshots and descriptions can be found in the Examples directory. For information on using the examples with different CLI options, refer to the CLI documentation.

ts-for-gir consists of several packages:

• @ts-for-gir/cli — Command-line interface for generating TypeScript definitions, documentation, and analyzing reports
• @gi.ts/parser — Parser for GObject Introspection XML files
• @ts-for-gir/lib — Core library for processing GIR data
• @ts-for-gir/reporter — Reporting system for problems and statistics with dependency injection
• @ts-for-gir/generator-typescript — TypeScript definition generator
• @ts-for-gir/generator-json — TypeDoc JSON generator with GIR metadata enrichment
• @ts-for-gir/generator-html-doc — HTML documentation generator using TypeDoc
• @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 — Template files for generated packages (tsconfig, typedoc config, ambient declarations)
• @ts-for-gir/tsconfig — Shared TypeScript configuration
• @ts-for-gir/language-server — Language server for GIR files (experimental)

This repo contains Git submodules for pre-generated types and documentation:

• types-dev (branch dev) — used during local development. Scripts write generated packages here.
• types-release (branch main) — updated by the release workflow on tags.
• docs (branch main) — generated HTML documentation, deployed to gjsify.github.io/docs.

Useful scripts:

gjsify run build:types          # regenerate into ./types-dev
gjsify run build:types:release  # regenerate into ./types-release
gjsify run build:doc            # build HTML docs into ./docs

• TypeScript API Documentation
• Examples
• CLI Documentation
• gjsify/types — pre-generated NPM packages
• gjsify/gnome-shell — hand-written Shell Extension types