TS for GIR

TypeScript type definition generator for GObject introspection GIR files

ts-for-gir reads GObject Introspection data and writes TypeScript definitions for GJS projects. Your editor then knows the whole GNOME stack: jump to definition, autocompletion, and a type error when you pass the wrong thing to g_object_set().

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

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

Quick Start

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>:

Template	Best for
types-gjsify	A GJS app with no Node.js. Install, build, run and format all go 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

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

Installation

GJS, without Node.js

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.

If you already have the gjsify CLI, skip that. gjsify dlx @ts-for-gir/cli <args> runs it without installing, gjsify install -g @ts-for-gir/cli installs it globally.

Node.js

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

CLI Usage

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.

Pre-generated NPM Packages

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.

Showcase

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

Example Projects

These example projects wire the definitions up with different bundlers:

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

The Examples directory has more, with screenshots. The CLI documentation covers running them under different CLI options.

Project Structure

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)

Submodules

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

Further Reading

• TypeScript API Documentation
• Examples
• CLI Documentation
• Using ts-for-gir as a library: building your own TSX or framework types from GIR, and which of the three routes needs no library at all
• gjsify/types: pre-generated NPM packages
• gjsify/gnome-shell: hand-written Shell Extension types