@d34/gjs-libs

Type-safe GObject Introspection for various GTK libraries for TypeScript projects.

What is this?

This package encapsulates gi:// protocol imports for GNOME libraries, allowing you to write TypeScript applications that run in the GJS runtime. It re-exports the @girs type definitions while handling the gi:// imports internally.

Note: This package does not include the actual GNOME libraries. They must be installed on the system where the GJS runtime executes your bundled code.

Intended Use

1. Develop your GJS application using Deno, Bun, or Node with full TypeScript support
2. Import GNOME libraries from this package with IDE autocompletion and type checking
3. Bundle your code into a JavaScript file
4. Execute the bundled output in the GJS runtime

Why not just use @girs/ packages directly?

All of the above can be done directly with the @girs packages, hovewer they expect you to use gi:// imports directly in the code, which makes it impossible to produce a reusable JSR package with these imports - this is the problem @d34/gjs-libs is aiming to solve

Why no JSR package?

JSR (JavaScript Registry) doesn't allow gi:// protocol imports. This package is distributed via npm to encapsulate those imports, enabling JSR-hosted packages to use GNOME libraries through this dependency.

Installation

# npm
npm install @d34/gjs-libs

# pnpm
pnpm add @d34/gjs-libs

# Deno
deno add npm:@d34/gjs-libs

Usage

Importing Libraries

// GTK 4
import Gtk from "@d34/gjs-libs/gtk-4.0";

// Adwaita
import Adw from "@d34/gjs-libs/adw-1";

// Core libraries
import GLib from "@d34/gjs-libs/glib-2.0";
import GObject from "@d34/gjs-libs/gobject-2.0";
import Gio from "@d34/gjs-libs/gio-2.0";

// GJS runtime
import Gjs from "@d34/gjs-libs/gjs";

Example: Simple GTK 4 Application

import Gtk from "@d34/gjs-libs/gtk-4.0";
import GLib from "@d34/gjs-libs/glib-2.0";

Gtk.init();

const app = new Gtk.Application({
  application_id: "com.example.MyApp",
});

app.connect("activate", () => {
  const window = new Gtk.ApplicationWindow({ application: app });
  window.set_title("Hello World");
  window.set_default_size(400, 300);

  const button = new Gtk.Button({ label: "Click me!" });
  button.connect("clicked", () => {
    console.log("Button clicked!");
  });

  window.set_child(button);
  window.present();
});

app.run([]);

Example: Adwaita Application

import Adw from "@d34/gjs-libs/adw-1";
import Gtk from "@d34/gjs-libs/gtk-4.0";
import Gio from "@d34/gjs-libs/gio-2.0";

const app = new Adw.Application({
  application_id: "com.example.AdwApp",
});

app.connect("activate", () => {
  const window = new Adw.ApplicationWindow({ application: app });

  const headerBar = new Adw.HeaderBar();
  const content = new Gtk.Box({
    orientation: Gtk.Orientation.VERTICAL,
    spacing: 12,
  });

  const toolbar = new Adw.ToolbarView();
  toolbar.add_top_bar(headerBar);
  toolbar.set_content(content);

  window.set_content(toolbar);
  window.present();
});

app.run([]);

How It Works

Each module re-exports from both the gi:// protocol (runtime) and @girs/* npm packages (types):

// @ts-types="@girs/gtk-4.0"
import Gtk from "gi://Gtk?version=4.0";
export default Gtk;
export * from "@girs/gtk-4.0";

• Types come from the @girs/* npm packages via the @ts-types directive
• Runtime imports use the gi:// protocol which GJS resolves to native GNOME libraries

Bundling and executing

Bundle your TypeScript code for GJS execution using your preferred bundler:

# esbuild
esbuild src/main.ts --bundle --outfile=dist/app.js --format=esm --external:'gi://*'

# Execute bundle in gjs
gjs dist/app.js

Make sure to mark gi://* as external so the bundler preserves these imports for GJS.

Available Libraries

This package includes 665 GNOME/GLib ecosystem libraries. Some commonly used ones:

Core

• glib-2.0 - GLib core utilities
• gobject-2.0 - GObject base class system
• gio-2.0 - GIO I/O library
• gjs - GJS runtime types

GUI

• gtk-4.0 - GTK 4 toolkit
• gtk-3.0 - GTK 3 toolkit (legacy)
• adw-1 - Libadwaita (GNOME UI patterns)
• gdk-4.0 - GDK 4 (windowing)
• gsk-4.0 - GSK 4 (rendering)

Graphics

• cairo-1.0 - Cairo 2D graphics
• pango-1.0 - Pango text rendering
• graphene-1.0 - Graphene math library
• gdkpixbuf-2.0 - Image loading

Multimedia

• gst-1.0 - GStreamer core
• gstbase-1.0 - GStreamer base classes
• gstaudio-1.0 - GStreamer audio
• gstvideo-1.0 - GStreamer video

Desktop Integration

• nm-1.0 - NetworkManager
• secret-1 - Secret Service (keyring)
• notify-0.7 - Desktop notifications
• polkit-1.0 - PolicyKit authorization

Web

• webkit-6.0 - WebKitGTK 6
• soup-3.0 - HTTP library
• json-1.0 - JSON-GLib

License

MIT

Credits

Type definitions provided by ts-for-gir / @girs.