TypeScript type definition generator for GObject introspection GIR files

ts-for-gir is a robust TypeScript type definitions generator that improves the development experience of GJS projects. It has been completely rewritten over time to provide a more complete and accurate TypeScript representation of the GObject introspection interfaces. With ts-for-gir, developers can now benefit from TypeScript's strong typing and improved code navigation, making it easier to build robust and powerful applications with GJS.

Browse the full TypeScript API Documentation for GLib, GTK, GStreamer, and many other GNOME libraries.

Install the latest LTS version of Node.js — we recommend using NVM. The fastest path to a working GJS + TypeScript project:

npx @ts-for-gir/cli create my-app

That scaffolds a ready-to-run starter with esbuild, tsconfig.json, and a minimal Gtk/Adwaita main.ts. Pick a template interactively — or pass --template <id>:

• types-npm — uses the pre-generated @girs/* NPM packages (fastest start)
• types-locally — generates types directly into ./@types/, no @girs/* dependencies
• types-workspace — npm workspace layout with locally-generated @girs/* as workspace packages

cd my-app
npm start

If you already have a project and just need type definitions, invoke ts-for-gir without scaffolding:

npx @ts-for-gir/cli generate Gtk-4.0

Run npx @ts-for-gir/cli --help for all commands. See the CLI documentation for detailed options and advanced usage.

Debug Generation Issues: If you encounter type generation problems, enable the reporter and use the analyze command:

npx @ts-for-gir/cli generate Gtk-4.0 --reporter
npx @ts-for-gir/cli analyze -f ./ts-for-gir-report.json

GNOME Applications

• Audio Player - Play audio files
• Counters - Keep track of anything
• Ignition - Manage startup apps and scripts
• Learn 6502 - Learn program 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.

If you are only interested in the types and do not want to generate them yourself, you can use our pre-generated NPM packages. For example, if you want to develop a Gtk4 application with GJS, it is enough to install the corresponding NPM packages:

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

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 pre-generated NPM packages can be found on gjsify/types.

You want your or any other missing GObject introspection based library types to be published on NPM for every release? Then feel free to create an issue for it, we will be happy to include it.

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:

yarn build:types          # generates into ./types-dev
yarn build:types:release  # generates into ./types-release
yarn build:doc            # generates HTML docs into ./docs

• TypeScript API Documentation - Browsable API reference for all GJS type definitions
• Examples - Detailed examples showing TypeScript with different bundlers
• CLI Documentation - Comprehensive guide to CLI options and features
• gjsify/types - Pre-generated NPM packages you can use directly
• GNOME Shell Extension Types - Hand-written type definitions for GNOME Shell Extensions