Examples

May 20, 2026 · View on GitHub

This directory contains various examples showing how to use TypeScript with GJS applications. Each example demonstrates different libraries, features, and bundlers to help you get started with your own projects.

About the Examples

Each example:

Uses TypeScript with GJS
Demonstrates TypeScript type definitions generated by ts-for-gir
Shows how to configure various bundlers or the TypeScript compiler
Can be used as a starting point for your own projects

To use an example:

Go to the example directory
Run gjsify install to install dependencies
Run gjsify run build to build the example
Run gjsify run start to run the example

Note: Examples must be built because GJS cannot execute TypeScript directly. However, the core ts-for-gir packages no longer require building and run directly as TypeScript files.

The examples use the @girs/* NPM packages for TypeScript definitions. These are pre-generated type definitions that you can also generate yourself using the ts-for-gir CLI with the --package option. For more information on CLI options, see the CLI documentation.

Quality Assurance and Testing

All examples in this directory are part of our Continuous Integration (CI) pipeline. They are:

Built during CI runs
Validated for TypeScript type correctness
Many are even executed as part of automated tests

This process ensures that our generated TypeScript definitions correctly match the GObject introspection data and work as expected in real applications. When issues with the type definitions are discovered, we often create or adapt examples to cover those edge cases and prevent regressions.

If you encounter a situation where the generated types don't work correctly, we encourage you to:

Create a minimal example demonstrating the issue
Submit it as a pull request
Or open an issue with details about the problem

This collaborative approach helps us improve the quality of the type definitions for everyone.

Available Examples

GTK 4 Examples

Example	Description	Bundler
GTK 4 Template (Blueprint + Vite)	Blueprint UI files with Vite plugin for direct import support	Vite
GTK 4 Template (Vite)	Modern UI with Vite for template and CSS loading	Vite
GTK 4 Template (esbuild)	Template-based UI using esbuild for asset loading	esbuild
GTK 4 Template (TSC)	Pure TypeScript compilation with runtime asset loading	TSC
GTK 4 Application	Basic GTK 4 application structure	esbuild
GTK 4 ListStore	Data management with TreeView and ListStore	esbuild
GTK 4 Custom Widget	Creating custom widgets and virtual functions	esbuild
GTK 4 Gettext	Internationalization with gettext	esbuild
GTK 4 Signal Helpers	Signal connection utilities and patterns	esbuild
GTK 4 Signal Interfaces	Advanced signal handling and interface patterns	esbuild

GTK 3 Examples

Example	Description	Bundler
GTK 3 Browser	Web browser using WebKit	Webpack
GTK 3 Builder	UI design with Glade/Builder	Webpack
GTK 3 Calculator	Simple calculator application	esbuild
GTK 3 Clutter	Graphics with Clutter integration	TSC
GTK 3 Editor	Text editor application	Parcel
GTK 3 Hello World	Minimal GTK 3 application	Rollup
GTK 3 Hello World 2	Alternative GTK 3 hello world	esbuild
GTK 3 Template	GTK 3 template-based UI	esbuild
GTK 3 WebKit	WebKit integration example	esbuild

Libadwaita Examples

Example	Description	Bundler
Adwaita Hello World	Modern GNOME UI with Libadwaita	Vite

Gio and GLib Examples

Example	Description	Bundler
Gio Action Entries	GAction and menu integration	esbuild
Gio Async Operations	Asynchronous file and network operations	esbuild
Gio Cat	File system operations with Gio	esbuild
Gio DBus	DBus client/server communication	esbuild
Gio Iteration	File and directory iteration	esbuild
Gio List Model	Virtual interface implementation example	esbuild
GLib Spawn Command	Process spawning and command execution	esbuild
GLib Types	GLib data types and utilities	esbuild
GLib Variant	GVariant serialization and handling	esbuild
GObject Param Spec	GObject property specifications	esbuild

Database Examples

Example	Description	Bundler
GOM SQLite ORM	SQLite ORM with GOM (insert, find, update, migrate)	esbuild
GDA SQLite	SQLite with libgda (raw SQL, SqlBuilder, DataModel)	esbuild

Cairo and Graphics Examples

Example	Description	Bundler
Cairo Drawing	2D graphics with Cairo	TSC
Clutter Graphics	3D graphics with Clutter	TSC

Network and Communication Examples

Example	Description	Bundler
Soup HTTP	HTTP client/server with Soup 3	esbuild
Soup WebSocket	WebSocket communication with Soup 3	esbuild

Utility and System Examples

Example	Description	Bundler
Console Application	Command-line application example	TSC
Package TSC	Package structure with TypeScript	TSC
Run Async	Asynchronous execution patterns	esbuild
ST Layout Manager	St layout management utilities	esbuild
Timers	Timer and scheduling examples	esbuild

Dependency Injection Examples

Example	Description	DI Library	Bundler
DI with Needle	GObject + automatic dependency resolution	Needle DI	esbuild
DI with Wise	Type-safe dependency injection with interfaces	di-wise	esbuild
DI with TSyringe	Traditional DI with parameter decorators	TSyringe	esbuild

Virtual Interface Examples

Example	Description	Bundler
Virtual Interface Test	Comprehensive virtual interface examples	esbuild

How to Run Examples

For most examples, you can use:

cd examples/<example-directory>
gjsify install
gjsify run start  # This will build and run the example

Some examples like the DBus and HTTP examples have separate client and server parts:

# For DBus example
cd examples/gio-2-dbus
gjsify install
gjsify run start:server  # In one terminal
gjsify run start:client  # In another terminal

# For HTTP example
cd examples/soup-3-http
gjsify install
gjsify run start:server  # In one terminal
gjsify run start:client  # In another terminal

TypeScript Configuration

Each example includes a tsconfig.json file that shows how to configure TypeScript for GJS applications. This typically includes:

Setting the module system to ESNext
Configuring the appropriate lib and types
Including the necessary GIR type declarations

For example:

{
  "compilerOptions": {   
    "lib": ["ESNext"],
    "types": ["@girs/gjs", "@girs/gjs/dom", "@girs/gio-2.0", "@girs/glib-2.0", "@girs/gtk-4.0", "@girs/adw-1"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Using with Different Type Generation Methods

The examples can be used with different methods of type generation:

Pre-generated NPM packages: Most examples use @girs/* packages from npm (e.g., @girs/gtk-4.0)
Local generation with CLI: You can generate types directly using the CLI:
```
npx @ts-for-gir/cli generate Gtk-4.0 --outdir ./@types
```

For more information on CLI options and type generation, see the CLI documentation.

Contributing Examples

Feel free to contribute new examples that showcase:

Different libraries from the GObject ecosystem
Different bundlers or build systems
Interesting UI patterns or application architectures
Advanced TypeScript features with GJS

If you discover cases where the generated type definitions don't work correctly, creating a minimal example that demonstrates the issue can be extremely helpful for us to fix it.