README.md

May 22, 2026 · View on GitHub

TS for GIR

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.

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

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

Installation

GJS — no Node.js required

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).

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

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.

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