API Reference / @gtkx/config / index / Config

Type Alias: Config

Config = object

Defined in: packages/config/src/config.ts:30

GTKX project configuration authored in gtkx.config.ts and validated when loaded.

Type Declaration

agents?

optional agents?: object

Controls the project instructions and reference files generated for coding agents.

agents.reference?

optional reference?: boolean

Whether codegen writes the generated element reference to .gtkx/reference. Defaults to true.

agents.rules?

optional rules?: boolean

Whether codegen maintains the GTKX rules in AGENTS.md and creates a missing CLAUDE.md import. Defaults to true.

applicationIcon?

optional applicationIcon?: string

Path to an icon theme directory or a single application icon file, relative to the project root.

applicationId

applicationId: string

Required GApplication identifier, such as com.example.Tasks.

codegen?

optional codegen?: boolean

Whether GTKX generates project bindings. Set to false to reuse an installed binding store. Defaults to true.

deploy?

optional deploy?: object

Application metadata, bundled runtime settings, and packaging options used by gtkx deploy.

deploy.appimage?

optional appimage?: object

AppImage packaging options.

deploy.appimage.compression?

optional compression?: "zstd"

Compression explicitly requested from appimagetool.

deploy.appimage.fileName?

optional fileName?: string

Output file name, derived from the application name, version, and architecture when omitted.

deploy.appimage.runtimeFile?

optional runtimeFile?: string

Custom AppImage runtime file path, resolved relative to the project root.

deploy.appimage.updateInformation?

optional updateInformation?: string

AppImage update information string embedded in the executable.

deploy.architectures?

optional architectures?: ("arm64" | "x64")[]

Target CPU architectures. Defaults to the host architecture; overridden by gtkx deploy --arch.

deploy.binaryName?

optional binaryName?: string

Launcher command name, derived from package.json's name or the application ID when omitted.

deploy.branding?

optional branding?: object

Primary branding colors included in AppStream metadata.

deploy.branding.dark

dark: string

Primary AppStream branding color for dark mode, in #rrggbb format.

deploy.branding.light

light: string

Primary AppStream branding color for light mode, in #rrggbb format.

deploy.categories?

optional categories?: string[]

Freedesktop application categories used by launchers, software centers, and package metadata.

deploy.contentRating?

optional contentRating?: Record<string, "none" | "intense" | "mild" | "moderate">

OARS 1.1 content-rating attributes mapped to their intensities.

deploy.copyright?

optional copyright?: string

Copyright notice. Defaults to the build year and developer name.

deploy.deb?

optional deb?: object

Debian package metadata and compression options.

deploy.deb.compression?

optional compression?: "gzip" | "none" | "xz" | "zstd"

Compression used for the Debian package payload.

deploy.deb.fields?

optional fields?: Record<string, string>

Additional Debian control fields, keyed by field name.

deploy.deb.packageName?

optional packageName?: string

Debian package name. Defaults to deploy.binaryName.

deploy.deb.priority?

optional priority?: string

Debian package priority. Defaults to optional.

deploy.deb.section?

optional section?: string

Debian archive section, derived from the application categories when omitted.

deploy.depends?

optional depends?: object

Additional Debian and RPM dependencies merged with automatically detected dependencies.

deploy.depends.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.depends.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.description?

optional description?: string[]

Long description as paragraphs. Defaults to the summary when omitted or empty.

deploy.desktopActions?

optional desktopActions?: Record<string, { args?: string[]; icon?: string; name: string; }>

Desktop launcher actions keyed by action ID.

See

DeployDesktopActionOptions for the fields accepted by each entry.

deploy.desktopEntry?

optional desktopEntry?: Record<string, string>

Additional desktop entry keys, overriding non-reserved generated values. DBusActivatable and Version are rejected; use deploy.isDbusActivatable for D-Bus activation.

deploy.developer?

optional developer?: object

Developer identity and package maintainer details.

deploy.developer.email?

optional email?: string

Maintainer email address. Defaults to the author's email in package.json.

deploy.developer.id?

optional id?: string

Reverse-DNS developer identifier, derived from the application ID when omitted.

deploy.developer.name?

optional name?: string

Developer or organization name. Defaults to the author in package.json.

deploy.epoch?

optional epoch?: number

Non-negative Debian and RPM version epoch, omitted from package metadata unless configured.

deploy.execArgs?

optional execArgs?: string[]

Application arguments included in the desktop entry's launch command.

deploy.extraFiles?

optional extraFiles?: Record<string, string | DeployExtraFileOptions>

Extra files keyed by destination inside the install prefix, with source paths relative to the project root.

deploy.fileAssociations?

optional fileAssociations?: object[]

File extensions and MIME types registered for the application.

See

DeployFileAssociationOptions for the fields accepted by each entry.

deploy.flatpak?

optional flatpak?: object

Flatpak runtime, sandbox, build, and distribution options.

deploy.flatpak.base?

optional base?: string

Optional Flatpak base application ID.

deploy.flatpak.baseVersion?

optional baseVersion?: string

Branch of the base application.

deploy.flatpak.branch?

optional branch?: string

Exported application branch. Defaults to stable.

deploy.flatpak.buildCommands?

optional buildCommands?: string[]

Additional shell commands appended to the application's Flatpak build commands.

deploy.flatpak.cleanup?

optional cleanup?: string[]

Patterns added to header, pkg-config, and static-library cleanup defaults. An empty array disables cleanup.

deploy.flatpak.finishArgs?

optional finishArgs?: string[]

Sandbox permissions added to display, IPC, and GPU defaults. Negations remove matching defaults.

deploy.flatpak.lockfile?

optional lockfile?: string

Lockfile path relative to the project root. Defaults to the selected package manager's standard lockfile.

deploy.flatpak.mode?

optional mode?: "prebuilt" | "source"

Package local build output or build from a pinned Git source inside the SDK. Defaults to prebuilt.

deploy.flatpak.modules?

optional modules?: unknown[]

Additional Flatpak manifest modules built before the application module.

deploy.flatpak.nodeExtension?

optional nodeExtension?: string

Node.js SDK extension used in source mode. Defaults to org.freedesktop.Sdk.Extension.node26.

deploy.flatpak.packageManager?

optional packageManager?: "npm" | "pnpm" | "yarn"

Package manager used for offline source builds, detected from the project's lockfiles when omitted.

deploy.flatpak.runtime?

optional runtime?: string

Flatpak runtime ID. Defaults to org.gnome.Platform.

deploy.flatpak.runtimeRepo?

optional runtimeRepo?: string

Runtime repository URL embedded in the bundle. Defaults to Flathub's .flatpakrepo URL.

deploy.flatpak.runtimeVersion?

optional runtimeVersion?: string

Flatpak runtime branch. Defaults to 50.

deploy.flatpak.sdk?

optional sdk?: string

Build SDK ID. Defaults to org.gnome.Sdk.

deploy.flatpak.sdkExtensions?

optional sdkExtensions?: string[]

Additional SDK extension IDs included in the build environment.

deploy.flatpak.shouldEmitBundle?

optional shouldEmitBundle?: boolean

Emit a .flatpak bundle in addition to the local repository. Defaults to true.

deploy.flatpak.shouldInstall?

optional shouldInstall?: boolean

Install the built application into the current user's Flatpak installation. Defaults to false.

deploy.flatpak.shouldUseRofilesFuse?

optional shouldUseRofilesFuse?: boolean

Allow flatpak-builder to use rofiles-fuse. Set to false where FUSE is unavailable.

deploy.flatpak.source?

optional source?: object

Git repository and revision used for source builds.

deploy.flatpak.source.commit?

optional commit?: string

Git commit to build. Defaults to the configured tag's commit or the current HEAD.

deploy.flatpak.source.tag?

optional tag?: string

Git tag to build, pinned to its commit when commit is omitted.

deploy.flatpak.source.url?

optional url?: string

Public HTTP or HTTPS Git repository URL. Defaults to the project's Git remote.

deploy.genericName?

optional genericName?: string

Generic application description shown by desktop launchers, such as Text Editor.

deploy.homepage?

optional homepage?: string

Application homepage URL. Defaults to the homepage in package.json.

deploy.isDbusActivatable?

optional isDbusActivatable?: boolean

Enable D-Bus activation in the desktop entry and generate a session bus service file. Defaults to false.

deploy.keywords?

optional keywords?: string[]

Search keywords included in the desktop entry and AppStream metadata.

deploy.launcherEnv?

optional launcherEnv?: Record<string, string>

Environment variables exported by the generated launcher. Keys must be POSIX environment names.

deploy.license?

optional license?: string

Application license as an SPDX expression. Defaults to the license in package.json.

deploy.licenseFile?

optional licenseFile?: string

License file path relative to the project root, detected from common LICENSE or COPYING names when omitted.

deploy.metadataLicense?

optional metadataLicense?: string

SPDX license expression for the AppStream metadata. Defaults to CC0-1.0.

deploy.metainfoExtra?

optional metainfoExtra?: string[]

Additional XML fragments appended to the AppStream component.

deploy.mimeTypes?

optional mimeTypes?: string[]

Supported MIME types, combined with types from file associations and URL protocols.

deploy.minimumLibraryVersions?

optional minimumLibraryVersions?: Record<string, string>

Minimum runtime library versions keyed by GIR library ID, used when deriving package dependencies.

deploy.name?

optional name?: string

Display name, derived from package.json's name or the application ID when omitted.

deploy.node?

optional node?: DeployNodeOptions

Node.js runtime bundled with prebuilt packages and launcher compile-cache settings.

deploy.nodeFlags?

optional nodeFlags?: string[]

Node.js flags placed before the application bundle in the generated launcher.

deploy.outDir?

optional outDir?: string

Deployment directory relative to the project root. Defaults to build, with packages in its out directory.

deploy.protocols?

optional protocols?: string[]

URL schemes handled by the application, registered as x-scheme-handler MIME types.

deploy.relations?

optional relations?: object

Additional package relationships for Debian and RPM.

deploy.relations.breaks?

optional breaks?: object

Debian packages made incompatible by installing this package. Uses the deb entries.

deploy.relations.breaks.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.breaks.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.conflicts?

optional conflicts?: object

Packages that cannot be installed alongside this package.

deploy.relations.conflicts.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.conflicts.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.preDepends?

optional preDepends?: object

Debian dependencies required before unpacking this package. Uses the deb entries.

deploy.relations.preDepends.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.preDepends.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.provides?

optional provides?: object

Package names or capabilities supplied by this package.

deploy.relations.provides.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.provides.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.recommends?

optional recommends?: object

Recommended packages that extend the application's functionality.

deploy.relations.recommends.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.recommends.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.replaces?

optional replaces?: object

Packages whose files this package may replace.

deploy.relations.replaces.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.replaces.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.suggests?

optional suggests?: object

Suggested companion packages.

deploy.relations.suggests.deb?

optional deb?: string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.suggests.rpm?

optional rpm?: string[]

Package relations expressed in RPM dependency syntax.

deploy.release?

optional release?: string

Debian packaging revision and RPM release. Defaults to 1.

deploy.releases?

optional releases?: object[]

AppStream release history, sorted newest first. Defaults to the application version and build date.

See

DeployReleaseOptions for the fields accepted by each entry.

deploy.rpm?

optional rpm?: object

RPM package metadata and compression options.

deploy.rpm.compression?

optional compression?: "gzip" | "xz" | "zstd" | "lzma"

Compression used for the RPM package payload.

deploy.rpm.group?

optional group?: string

RPM package group, derived from the application categories when omitted.

deploy.rpm.packageName?

optional packageName?: string

RPM package name. Defaults to deploy.binaryName.

deploy.rpm.prefixes?

optional prefixes?: string[]

Installation prefixes that the RPM package allows users to relocate.

deploy.screenshotBaseUrl?

optional screenshotBaseUrl?: string

Base URL for screenshot files, inferred from a GitHub or GitLab remote when omitted.

deploy.screenshots?

optional screenshots?: object[]

Screenshots for software centers. Each entry requires a url or file.

See

DeployScreenshotOptions for the fields accepted by each entry.

deploy.scripts?

optional scripts?: object

Installation and removal scripts for Debian and RPM packages.

deploy.scripts.postInstall?

optional postInstall?: string

Shell script run after installing a Debian or RPM package.

deploy.scripts.postRemove?

optional postRemove?: string

Shell script run after removing a Debian or RPM package.

deploy.scripts.preInstall?

optional preInstall?: string

Shell script run before installing a Debian or RPM package.

deploy.scripts.preRemove?

optional preRemove?: string

Shell script run before removing a Debian or RPM package.

deploy.signing?

optional signing?: object

Per-format package signing options.

deploy.signing.appimage?

optional appimage?: object

AppImage signing options.

deploy.signing.appimage.gpgKeyId

gpgKeyId: string

GPG key ID used by appimagetool to sign the AppImage.

deploy.signing.deb?

optional deb?: object

Debian package signing options.

deploy.signing.deb.keyFile

keyFile: string

PGP private key file used to sign the Debian package.

deploy.signing.deb.keyId?

optional keyId?: string

PGP signing key ID.

deploy.signing.deb.method?

optional method?: "debsign" | "dpkg-sig"

Debian package signing method.

deploy.signing.deb.signer?

optional signer?: string

Name and email address recorded as the signer.

deploy.signing.deb.type?

optional type?: "origin" | "archive" | "maint"

Debian signature role.

deploy.signing.flatpak?

optional flatpak?: object

Flatpak bundle signing options.

deploy.signing.flatpak.gpgHomeDir?

optional gpgHomeDir?: string

GPG home directory containing the signing key.

deploy.signing.flatpak.gpgKeyId

gpgKeyId: string

GPG key ID used to sign the Flatpak bundle.

deploy.signing.rpm?

optional rpm?: object

RPM package signing options.

deploy.signing.rpm.keyFile

keyFile: string

PGP private key file used to sign the RPM package.

deploy.signing.rpm.keyId?

optional keyId?: string

PGP signing key ID.

deploy.summary?

optional summary?: string

Single-line summary without a trailing period. Defaults to the first line of package.json's description.

deploy.targets?

optional targets?: ("appimage" | "deb" | "flatpak" | "rpm")[]

Package formats to build. Defaults to ["flatpak"]; overridden by gtkx deploy --target.

deploy.urls?

optional urls?: Partial<Record<"bugtracker" | "contact" | "contribute" | "donation" | "faq" | "help" | "translate" | "vcs-browser", string>>

Additional AppStream links keyed by their purpose, such as bugtracker or help.

deploy.version?

optional version?: string

Application version. Defaults to the version in package.json.

deprecations?

optional deprecations?: object

Controls warnings for deprecated configuration and behavior.

deprecations.silence?

optional silence?: never[]

Deprecation identifiers whose warnings are suppressed. There are currently no accepted identifiers.

elements?

optional elements?: object

Custom element behaviors and overrides for generated components, props, and documentation.

elements.behaviors?

optional behaviors?: string

Path, relative to the project root, of the module exporting the element behavior map.

elements.config?

optional config?: Record<string, { acceptedChildTypes?: string[]; component?: { export: string; module: string; }; isLazy?: boolean; omittedProps?: string[]; props?: { composition?: "intersection" | "factory"; constructOnly?: string[]; export: string; module: string; }; }>

Element configuration overrides keyed by GLib type name, such as GtkWidget.

See

ElementConfigOptions for the fields accepted by each entry.

girPath?

optional girPath?: string[]

Additional GIR search directories. Relative paths are resolved from the project root.

libraries?

optional libraries?: string[]

Additional GIR libraries to bind, such as WebKit-6.0. Adwaita and GTK are included implicitly and must not be listed.

mcp?

optional mcp?: object

Default tool selection and access mode for the project's MCP server. Command-line flags take precedence.

mcp.readOnly?

optional readOnly?: boolean

Whether the MCP server exposes only inspection and reference tools, excluding app interactions. Defaults to false.

mcp.tools?

optional tools?: string[]

Tool name patterns applied in order: * matches any text and a leading ! excludes matches. Omitted, empty, or exclusion-only lists start with all tools; other lists start with none.

reactCompiler?

optional reactCompiler?: boolean | { compilationMode?: "infer" | "syntax" | "annotation" | "all"; panicThreshold?: "none" | "critical_errors" | "all_errors"; }

Whether to enable the React Compiler, or options passed to it. Enabled by default.

Union Members

boolean

---

Type Literal

{ compilationMode?: "infer" | "syntax" | "annotation" | "all"; panicThreshold?: "none" | "critical_errors" | "all_errors"; }

compilationMode?

optional compilationMode?: "infer" | "syntax" | "annotation" | "all"

Which functions the React Compiler processes.

panicThreshold?

optional panicThreshold?: "none" | "critical_errors" | "all_errors"

Which React Compiler diagnostics fail the build.

userEventSignals?

optional userEventSignals?: Record<string, string[]>

Additional signals to suppress during React property updates, keyed by GLib type name. Entries extend the built-in signal lists.