# __APP_NAME__

An [Adwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/) application built
with [node-gtk](https://github.com/romgrk/node-gtk) and TypeScript.

## Prerequisites

You need GTK 4 and libadwaita — plus their GObject-Introspection data — installed
on your system. node-gtk talks to the libraries you actually have installed.

- **Fedora:** `sudo dnf install gtk4-devel libadwaita-devel gobject-introspection-devel`
- **Debian/Ubuntu:** `sudo apt install libgtk-4-dev libadwaita-1-dev gobject-introspection`
- **Arch:** `sudo pacman -S gtk4 libadwaita gobject-introspection`
- **macOS (Homebrew):** `brew install gtk4 libadwaita gobject-introspection`

The `-dev`/`-devel` packages also ship the `.gir` files used to embed GNOME's API
documentation into the generated TypeScript types (shown on hover in your editor).

You also need **Node.js ≥ 20.6** (for the `gi:` import hooks).

## Getting started

```sh
npm install        # installs deps and generates TypeScript types (postinstall)
npm run dev        # run the app with live reload
```

That's it — a window should appear. Edit `style.css` while it runs and the
window restyles instantly, no restart. To also restart the app when you edit
`src/`, run `npm run dev:app-reload` instead (it adds `node --watch`).

## How it works

Namespaces are imported with the `gi:` scheme, and their default export is the
namespace object:

```ts
import Gtk from 'gi:Gtk-4.0'
import Adw from 'gi:Adw-1'
```

For those imports to resolve, node-gtk's loader hooks must be installed, which is
why the app is run with `node --import node-gtk/register`. The `dev`/`start`
scripts already include this (along with `tsx`, which runs the TypeScript without
a separate build step). node-gtk integrates the GTK main loop with Node's event
loop automatically.

## Scripts

| command                  | what it does                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| `npm run dev`            | Run with live CSS reload — edit `style.css`, the window restyles, no restart. |
| `npm run dev:app-reload` | Like `dev`, but also restarts the app when you edit `src/` (`node --watch`). |
| `npm start`              | Run once without building.                                        |
| `npm run build`     | Type-check and compile `src/` to `dist/` with `tsc`.             |
| `npm run typecheck` | Type-check only, no output.                                      |
| `npm run generate-types` | (Re)generate TypeScript types for the GI namespaces you use. |

## TypeScript types

Types are generated **on your machine** from the GObject-Introspection typelibs
you have installed, so they match your actual library versions and node-gtk's
runtime shape (camelCase methods, typed signals, nullability, …). They live in
`node_modules/.node-gtk-types/` (git-ignored) and `tsconfig.json` points at them.

The `postinstall` script regenerates them automatically. If you start using
another library, add it to the `generate-types` script in `package.json` and
re-run it:

```jsonc
// package.json
"generate-types": "node-gtk generate-types Gtk-4.0 Adw-1 GtkSource-5"
```

```sh
npm run generate-types
```

## Project structure

```
.
├── src/
│   ├── main.ts        # the application entry point
│   └── welcome.ts     # a component with its own inline, hot-reloadable styles
├── style.css          # custom CSS (hot-reloads live under `npm run dev`)
├── tsconfig.json
└── package.json
```

## Learn more

- [node-gtk](https://github.com/romgrk/node-gtk) — the bindings
- [Importing libraries](https://github.com/romgrk/node-gtk/blob/master/doc/importing.md) — the `gi:` scheme and ESM details
- [GTK 4 API reference](https://docs.gtk.org/gtk4/)
- [libadwaita API reference](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/)
- [Adwaita style classes](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html)