README.md

August 28, 2026 ยท View on GitHub

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

TemplateBest for
types-gjsifyA GJS app with no Node.js. Install, build, run and format all go through gjsify
types-npmSingle-package, types from @girs/* NPM, esbuild + node
types-locallyGenerate types into ./@types/ (no @girs/* dep)
types-workspacenpm 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

GNOME Shell Extensions

Example Projects

These example projects wire the definitions up with different bundlers:

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:

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