Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/devhammed/react-gtk/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before installing React GTK, ensure you have the following dependencies installed on your system:
GJS is the GNOME JavaScript runtime that provides JavaScript bindings for GNOME libraries including GTK.Install on Ubuntu/Debian:
sudo apt install gjs
Install on Fedora:
sudo dnf install gjs
Install on Arch Linux:
sudo pacman -S gjs
Verify installation:
gjs --version
GTK 4.0 is required for React GTK to work. Most modern Linux distributions include GTK 4.Install on Ubuntu/Debian:
sudo apt install libgtk-4-1 libgtk-4-dev
Install on Fedora:
sudo dnf install gtk4 gtk4-devel
Install on Arch Linux:
sudo pacman -S gtk4
GTK 4.0 or later is required. React GTK does not support GTK 3.x.
Node.js is required for building your React GTK applications with bundlers.Install Node.js 16.x or later:
node --version  # Should be 16.x or higher
npm --version

​
Install React GTK

Once you have the prerequisites installed, you can add React GTK to your project.
1

Create a new project directory

mkdir my-gtk-app
cd my-gtk-app
npm init -y
2

Install React GTK and React

Install the react-gtk-renderer package along with React:
npm install react-gtk-renderer react
React GTK requires React 18.0 or higher as a peer dependency.
3

Install development dependencies

For TypeScript support and building your application, install these development dependencies:
npm install -D typescript parcel @parcel/packager-ts @parcel/transformer-typescript-types
While TypeScript is optional, it’s highly recommended for the best development experience with full type definitions.

​
Project setup

After installation, set up your project structure and configuration files.

​
TypeScript configuration

Create a tsconfig.json file in your project root:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"],
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

​
Package.json scripts

Add build and run scripts to your package.json:
package.json
{
  "name": "my-gtk-app",
  "version": "1.0.0",
  "source": "src/index.tsx",
  "scripts": {
    "build": "parcel build --no-source-maps",
    "start": "parcel watch --no-source-maps --no-hmr",
    "app": "gjs dist/index.js",
    "clean": "rm -rf dist"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-gtk-renderer": "^1.0.6"
  },
  "devDependencies": {
    "parcel": "^2.8.3",
    "typescript": "^4.9.4",
    "@parcel/packager-ts": "^2.8.3",
    "@parcel/transformer-typescript-types": "^2.8.3"
  }
}

​
Project structure

Create the following directory structure: 
my-gtk-app/
├── src/
│   ├── index.tsx          # Application entry point
│   └── components/
│       └── app.tsx        # Main app component
├── dist/                  # Build output (generated)
├── package.json
└── tsconfig.json
The src/ directory contains your source code, and Parcel will compile everything into the dist/ directory.

​
Verify installation

To verify that everything is installed correctly, create a simple test file:
src/index.tsx
import { createRoot, GtkWindow, GtkLabel } from 'react-gtk-renderer';

declare const imports: any;

imports.package.init({
  name: 'com.example.test',
  version: '1.0.0',
  prefix: '/usr',
  libdir: '/usr/lib',
  pkgdatadir: '/usr/share'
});

imports.package.run({
  main: function (argv: string[]) {
    const root = createRoot({ id: 'com.example.test' });
    
    root.render(
      <GtkWindow title="Test App" defaultWidth={400} defaultHeight={300}>
        <GtkLabel label="React GTK is installed!" />
      </GtkWindow>,
      argv
    );
  }
});
Build and run: 
npm run build
npm run app
You should see a GTK window with the text “React GTK is installed!”.
If the window appears, congratulations! React GTK is installed and working correctly.

​
Troubleshooting

If you get an error that gjs command is not found:
  1. Ensure GJS is installed: sudo apt install gjs (or equivalent for your distro)
  2. Verify it’s in your PATH: which gjs
  3. Check the version: gjs --version
If you get errors about missing GTK 4.0:
  1. Install GTK 4 development packages: sudo apt install libgtk-4-1 libgtk-4-dev
  2. Verify installation: pkg-config --modversion gtk4
If Parcel fails to build:
  1. Ensure you have all Parcel plugins installed: 
    npm install -D @parcel/packager-ts @parcel/transformer-typescript-types
  2. Clear Parcel cache: rm -rf .parcel-cache
  3. Try rebuilding: npm run clean && npm run build
If you get TypeScript errors:
  1. Ensure tsconfig.json has "jsx": "react"
  2. Check that React types are available (they’re included with React 18+)
  3. Verify react-gtk-renderer includes its type definitions

​
Next steps

Quickstart tutorial

Build your first React GTK application with a step-by-step tutorial

Core concepts

Learn how React GTK renders components and manages widgets

GTK components

Explore all available GTK widgets as React components

Examples

See complete example applications

Build docs developers (and LLMs) love

Get started for freeTalk to us