TypeScript for GNOME Shell

Write GNOME Shell Extensions in TypeScript

Overview

This project provides TypeScript type definitions for GNOME Shell Extensions. It aims to make the development of GNOME Shell Extensions in TypeScript more intuitive and efficient. The project is currently in an experimental phase and greatly benefits from community contributions.

How It Works

The TypeScript types for the used libraries are generated from the .gir files using ts-for-gir and are available as NPM packages. A significant portion of GNOME Shell is written in JavaScript, lacking .gir files. Therefore, these type definitions need to be manually created, which is the primary focus of this project. These additional definitions are manually written and included in this repository. Our build scripts automatically generate *.js (for ESM) and *.cjs files, Ambient Module Definitions, and index files. The structure for these files can be found on ./packages/gnome-shell/src and should align with the structure of GNOME Shell's JavaScript source code, available here. This setup allows contributors to primarily focus on the TypeScript type definitions, with the rest being automatically generated, including the exports in the package.json.

Showcase

gTile is a fully typed Gnome extension for tiling and resizing windows
Pano is a fully typed Gnome extension that serves as the next-gen Clipboard Manager

We are happy if you link your project through a PR here 😊

Contributing

Every contribution, regardless of its size, is incredibly valuable. If you're using these types and discover missing types necessary for your GNOME Shell Extension, contributing just those types is immensely helpful. This approach ensures the types are tested in real-world scenarios, vital for a project as extensive as the GNOME Shell.

Getting Started:

To add TypeScript type definitions, mimic the data structure of the GNOME Shell's JavaScript source code.
Contributions can range from adding a few types you need for your project to more extensive contributions.

Development Instructions:

Build the types:

yarn build:types
# or
cd ./packages/gnome-shell
yarn build

Validate the types:

yarn validate:types

# or
cd ./packages/gnome-shell
yarn validate

Build the example:

yarn build:example

# or
cd ./examples/hello-world
yarn build

Validate the example:

yarn validate:example

# or
cd ./examples/hello-world
yarn validate

How to Contribute:

Fork this repository.
Create a new branch for your contribution.
Make your changes.
Submit a pull request with a clear description of the improvements or additions.

Your contributions help in building a comprehensive type definition resource for GNOME Shell Extensions, which in turn fosters a wider adoption and, subsequently, more contributions.

Contact and Support

For any questions or support, feel free to open an issue in the repository.

Thank you for contributing to the GNOME Shell Type Definitions project!

gjsify/gnome-shell