API Reference / @gtkx/config / index / mergeConfig

Function: mergeConfig()

mergeConfig(base, override): object

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

Deep-merges a configuration over a base. override wins over base on conflicting scalar and object keys, while arrays are concatenated with the override entries first.

Parameters

base

agents?

{ reference?: boolean; rules?: boolean; }

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

agents.reference?

boolean

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

agents.rules?

boolean

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

applicationIcon?

string

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

applicationId

string

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

codegen?

boolean

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

deploy?

{ appimage?: { compression?: "zstd"; fileName?: string; runtimeFile?: string; updateInformation?: string; }; architectures?: ("arm64" | "x64")[]; binaryName?: string; branding?: { dark: string; light: string; }; categories?: string[]; contentRating?: Record<string, "none" | "intense" | "mild" | "moderate">; copyright?: string; deb?: { compression?: "gzip" | "none" | "xz" | "zstd"; fields?: Record<string, string>; packageName?: string; priority?: string; section?: string; }; depends?: { deb?: string[]; rpm?: string[]; }; description?: string[]; desktopActions?: Record<string, { args?: string[]; icon?: string; name: string; }>; desktopEntry?: Record<string, string>; developer?: { email?: string; id?: string; name?: string; }; epoch?: number; execArgs?: string[]; extraFiles?: Record<string, string | DeployExtraFileOptions>; fileAssociations?: object[]; flatpak?: { base?: string; baseVersion?: string; branch?: string; buildCommands?: string[]; cleanup?: string[]; finishArgs?: string[]; lockfile?: string; mode?: "prebuilt" | "source"; modules?: unknown[]; nodeExtension?: string; packageManager?: "npm" | "pnpm" | "yarn"; runtime?: string; runtimeRepo?: string; runtimeVersion?: string; sdk?: string; sdkExtensions?: string[]; shouldEmitBundle?: boolean; shouldInstall?: boolean; shouldUseRofilesFuse?: boolean; source?: { commit?: string; tag?: string; url?: string; }; }; genericName?: string; homepage?: string; isDbusActivatable?: boolean; keywords?: string[]; launcherEnv?: Record<string, string>; license?: string; licenseFile?: string; metadataLicense?: string; metainfoExtra?: string[]; mimeTypes?: string[]; minimumLibraryVersions?: Record<string, string>; name?: string; node?: DeployNodeOptions; nodeFlags?: string[]; outDir?: string; protocols?: string[]; relations?: { breaks?: { deb?: string[]; rpm?: string[]; }; conflicts?: { deb?: string[]; rpm?: string[]; }; preDepends?: { deb?: string[]; rpm?: string[]; }; provides?: { deb?: string[]; rpm?: string[]; }; recommends?: { deb?: string[]; rpm?: string[]; }; replaces?: { deb?: string[]; rpm?: string[]; }; suggests?: { deb?: string[]; rpm?: string[]; }; }; release?: string; releases?: object[]; rpm?: { compression?: "gzip" | "xz" | "zstd" | "lzma"; group?: string; packageName?: string; prefixes?: string[]; }; screenshotBaseUrl?: string; screenshots?: object[]; scripts?: { postInstall?: string; postRemove?: string; preInstall?: string; preRemove?: string; }; signing?: { appimage?: { gpgKeyId: string; }; deb?: { keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }; flatpak?: { gpgHomeDir?: string; gpgKeyId: string; }; rpm?: { keyFile: string; keyId?: string; }; }; summary?: string; targets?: ("appimage" | "deb" | "flatpak" | "rpm")[]; urls?: Partial<Record<"bugtracker" | "contact" | "contribute" | "donation" | "faq" | "help" | "translate" | "vcs-browser", string>>; version?: string; }

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

deploy.appimage?

{ compression?: "zstd"; fileName?: string; runtimeFile?: string; updateInformation?: string; }

AppImage packaging options.

deploy.appimage.compression?

"zstd"

Compression explicitly requested from appimagetool.

deploy.appimage.fileName?

string

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

deploy.appimage.runtimeFile?

string

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

deploy.appimage.updateInformation?

string

AppImage update information string embedded in the executable.

deploy.architectures?

("arm64" | "x64")[]

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

deploy.binaryName?

string

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

deploy.branding?

{ dark: string; light: string; }

Primary branding colors included in AppStream metadata.

deploy.branding.dark

string

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

deploy.branding.light

string

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

deploy.categories?

string[]

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

deploy.contentRating?

Record<string, "none" | "intense" | "mild" | "moderate">

OARS 1.1 content-rating attributes mapped to their intensities.

deploy.copyright?

string

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

deploy.deb?

{ compression?: "gzip" | "none" | "xz" | "zstd"; fields?: Record<string, string>; packageName?: string; priority?: string; section?: string; }

Debian package metadata and compression options.

deploy.deb.compression?

"gzip" | "none" | "xz" | "zstd"

Compression used for the Debian package payload.

deploy.deb.fields?

Record<string, string>

Additional Debian control fields, keyed by field name.

deploy.deb.packageName?

string

Debian package name. Defaults to deploy.binaryName.

deploy.deb.priority?

string

Debian package priority. Defaults to optional.

deploy.deb.section?

string

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

deploy.depends?

{ deb?: string[]; rpm?: string[]; }

Additional Debian and RPM dependencies merged with automatically detected dependencies.

deploy.depends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.depends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.description?

string[]

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

deploy.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?

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?

{ email?: string; id?: string; name?: string; }

Developer identity and package maintainer details.

deploy.developer.email?

string

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

deploy.developer.id?

string

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

deploy.developer.name?

string

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

deploy.epoch?

number

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

deploy.execArgs?

string[]

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

deploy.extraFiles?

Record<string, string | DeployExtraFileOptions>

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

deploy.fileAssociations?

object[]

File extensions and MIME types registered for the application.

See

DeployFileAssociationOptions for the fields accepted by each entry.

deploy.flatpak?

{ base?: string; baseVersion?: string; branch?: string; buildCommands?: string[]; cleanup?: string[]; finishArgs?: string[]; lockfile?: string; mode?: "prebuilt" | "source"; modules?: unknown[]; nodeExtension?: string; packageManager?: "npm" | "pnpm" | "yarn"; runtime?: string; runtimeRepo?: string; runtimeVersion?: string; sdk?: string; sdkExtensions?: string[]; shouldEmitBundle?: boolean; shouldInstall?: boolean; shouldUseRofilesFuse?: boolean; source?: { commit?: string; tag?: string; url?: string; }; }

Flatpak runtime, sandbox, build, and distribution options.

deploy.flatpak.base?

string

Optional Flatpak base application ID.

deploy.flatpak.baseVersion?

string

Branch of the base application.

deploy.flatpak.branch?

string

Exported application branch. Defaults to stable.

deploy.flatpak.buildCommands?

string[]

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

deploy.flatpak.cleanup?

string[]

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

deploy.flatpak.finishArgs?

string[]

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

deploy.flatpak.lockfile?

string

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

deploy.flatpak.mode?

"prebuilt" | "source"

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

deploy.flatpak.modules?

unknown[]

Additional Flatpak manifest modules built before the application module.

deploy.flatpak.nodeExtension?

string

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

deploy.flatpak.packageManager?

"npm" | "pnpm" | "yarn"

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

deploy.flatpak.runtime?

string

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

deploy.flatpak.runtimeRepo?

string

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

deploy.flatpak.runtimeVersion?

string

Flatpak runtime branch. Defaults to 50.

deploy.flatpak.sdk?

string

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

deploy.flatpak.sdkExtensions?

string[]

Additional SDK extension IDs included in the build environment.

deploy.flatpak.shouldEmitBundle?

boolean

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

deploy.flatpak.shouldInstall?

boolean

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

deploy.flatpak.shouldUseRofilesFuse?

boolean

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

deploy.flatpak.source?

{ commit?: string; tag?: string; url?: string; }

Git repository and revision used for source builds.

deploy.flatpak.source.commit?

string

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

deploy.flatpak.source.tag?

string

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

deploy.flatpak.source.url?

string

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

deploy.genericName?

string

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

deploy.homepage?

string

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

deploy.isDbusActivatable?

boolean

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

deploy.keywords?

string[]

Search keywords included in the desktop entry and AppStream metadata.

deploy.launcherEnv?

Record<string, string>

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

deploy.license?

string

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

deploy.licenseFile?

string

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

deploy.metadataLicense?

string

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

deploy.metainfoExtra?

string[]

Additional XML fragments appended to the AppStream component.

deploy.mimeTypes?

string[]

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

deploy.minimumLibraryVersions?

Record<string, string>

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

deploy.name?

string

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

deploy.node?

DeployNodeOptions

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

deploy.nodeFlags?

string[]

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

deploy.outDir?

string

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

deploy.protocols?

string[]

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

deploy.relations?

{ breaks?: { deb?: string[]; rpm?: string[]; }; conflicts?: { deb?: string[]; rpm?: string[]; }; preDepends?: { deb?: string[]; rpm?: string[]; }; provides?: { deb?: string[]; rpm?: string[]; }; recommends?: { deb?: string[]; rpm?: string[]; }; replaces?: { deb?: string[]; rpm?: string[]; }; suggests?: { deb?: string[]; rpm?: string[]; }; }

Additional package relationships for Debian and RPM.

deploy.relations.breaks?

{ deb?: string[]; rpm?: string[]; }

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

deploy.relations.breaks.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.breaks.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.conflicts?

{ deb?: string[]; rpm?: string[]; }

Packages that cannot be installed alongside this package.

deploy.relations.conflicts.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.conflicts.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.preDepends?

{ deb?: string[]; rpm?: string[]; }

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

deploy.relations.preDepends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.preDepends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.provides?

{ deb?: string[]; rpm?: string[]; }

Package names or capabilities supplied by this package.

deploy.relations.provides.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.provides.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.recommends?

{ deb?: string[]; rpm?: string[]; }

Recommended packages that extend the application's functionality.

deploy.relations.recommends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.recommends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.replaces?

{ deb?: string[]; rpm?: string[]; }

Packages whose files this package may replace.

deploy.relations.replaces.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.replaces.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.suggests?

{ deb?: string[]; rpm?: string[]; }

Suggested companion packages.

deploy.relations.suggests.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.suggests.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.release?

string

Debian packaging revision and RPM release. Defaults to 1.

deploy.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?

{ compression?: "gzip" | "xz" | "zstd" | "lzma"; group?: string; packageName?: string; prefixes?: string[]; }

RPM package metadata and compression options.

deploy.rpm.compression?

"gzip" | "xz" | "zstd" | "lzma"

Compression used for the RPM package payload.

deploy.rpm.group?

string

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

deploy.rpm.packageName?

string

RPM package name. Defaults to deploy.binaryName.

deploy.rpm.prefixes?

string[]

Installation prefixes that the RPM package allows users to relocate.

deploy.screenshotBaseUrl?

string

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

deploy.screenshots?

object[]

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

See

DeployScreenshotOptions for the fields accepted by each entry.

deploy.scripts?

{ postInstall?: string; postRemove?: string; preInstall?: string; preRemove?: string; }

Installation and removal scripts for Debian and RPM packages.

deploy.scripts.postInstall?

string

Shell script run after installing a Debian or RPM package.

deploy.scripts.postRemove?

string

Shell script run after removing a Debian or RPM package.

deploy.scripts.preInstall?

string

Shell script run before installing a Debian or RPM package.

deploy.scripts.preRemove?

string

Shell script run before removing a Debian or RPM package.

deploy.signing?

{ appimage?: { gpgKeyId: string; }; deb?: { keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }; flatpak?: { gpgHomeDir?: string; gpgKeyId: string; }; rpm?: { keyFile: string; keyId?: string; }; }

Per-format package signing options.

deploy.signing.appimage?

{ gpgKeyId: string; }

AppImage signing options.

deploy.signing.appimage.gpgKeyId

string

GPG key ID used by appimagetool to sign the AppImage.

deploy.signing.deb?

{ keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }

Debian package signing options.

deploy.signing.deb.keyFile

string

PGP private key file used to sign the Debian package.

deploy.signing.deb.keyId?

string

PGP signing key ID.

deploy.signing.deb.method?

"debsign" | "dpkg-sig"

Debian package signing method.

deploy.signing.deb.signer?

string

Name and email address recorded as the signer.

deploy.signing.deb.type?

"origin" | "archive" | "maint"

Debian signature role.

deploy.signing.flatpak?

{ gpgHomeDir?: string; gpgKeyId: string; }

Flatpak bundle signing options.

deploy.signing.flatpak.gpgHomeDir?

string

GPG home directory containing the signing key.

deploy.signing.flatpak.gpgKeyId

string

GPG key ID used to sign the Flatpak bundle.

deploy.signing.rpm?

{ keyFile: string; keyId?: string; }

RPM package signing options.

deploy.signing.rpm.keyFile

string

PGP private key file used to sign the RPM package.

deploy.signing.rpm.keyId?

string

PGP signing key ID.

deploy.summary?

string

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

deploy.targets?

("appimage" | "deb" | "flatpak" | "rpm")[]

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

deploy.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?

string

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

deprecations?

{ silence?: never[]; }

Controls warnings for deprecated configuration and behavior.

deprecations.silence?

never[]

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

elements?

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

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

elements.behaviors?

string

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

elements.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?

string[]

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

libraries?

string[]

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

mcp?

{ readOnly?: boolean; tools?: string[]; }

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

mcp.readOnly?

boolean

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

mcp.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?

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.

userEventSignals?

Record<string, string[]>

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

override

agents?

{ reference?: boolean; rules?: boolean; }

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

agents.reference?

boolean

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

agents.rules?

boolean

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

applicationIcon?

string

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

applicationId

string

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

codegen?

boolean

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

deploy?

{ appimage?: { compression?: "zstd"; fileName?: string; runtimeFile?: string; updateInformation?: string; }; architectures?: ("arm64" | "x64")[]; binaryName?: string; branding?: { dark: string; light: string; }; categories?: string[]; contentRating?: Record<string, "none" | "intense" | "mild" | "moderate">; copyright?: string; deb?: { compression?: "gzip" | "none" | "xz" | "zstd"; fields?: Record<string, string>; packageName?: string; priority?: string; section?: string; }; depends?: { deb?: string[]; rpm?: string[]; }; description?: string[]; desktopActions?: Record<string, { args?: string[]; icon?: string; name: string; }>; desktopEntry?: Record<string, string>; developer?: { email?: string; id?: string; name?: string; }; epoch?: number; execArgs?: string[]; extraFiles?: Record<string, string | DeployExtraFileOptions>; fileAssociations?: object[]; flatpak?: { base?: string; baseVersion?: string; branch?: string; buildCommands?: string[]; cleanup?: string[]; finishArgs?: string[]; lockfile?: string; mode?: "prebuilt" | "source"; modules?: unknown[]; nodeExtension?: string; packageManager?: "npm" | "pnpm" | "yarn"; runtime?: string; runtimeRepo?: string; runtimeVersion?: string; sdk?: string; sdkExtensions?: string[]; shouldEmitBundle?: boolean; shouldInstall?: boolean; shouldUseRofilesFuse?: boolean; source?: { commit?: string; tag?: string; url?: string; }; }; genericName?: string; homepage?: string; isDbusActivatable?: boolean; keywords?: string[]; launcherEnv?: Record<string, string>; license?: string; licenseFile?: string; metadataLicense?: string; metainfoExtra?: string[]; mimeTypes?: string[]; minimumLibraryVersions?: Record<string, string>; name?: string; node?: DeployNodeOptions; nodeFlags?: string[]; outDir?: string; protocols?: string[]; relations?: { breaks?: { deb?: string[]; rpm?: string[]; }; conflicts?: { deb?: string[]; rpm?: string[]; }; preDepends?: { deb?: string[]; rpm?: string[]; }; provides?: { deb?: string[]; rpm?: string[]; }; recommends?: { deb?: string[]; rpm?: string[]; }; replaces?: { deb?: string[]; rpm?: string[]; }; suggests?: { deb?: string[]; rpm?: string[]; }; }; release?: string; releases?: object[]; rpm?: { compression?: "gzip" | "xz" | "zstd" | "lzma"; group?: string; packageName?: string; prefixes?: string[]; }; screenshotBaseUrl?: string; screenshots?: object[]; scripts?: { postInstall?: string; postRemove?: string; preInstall?: string; preRemove?: string; }; signing?: { appimage?: { gpgKeyId: string; }; deb?: { keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }; flatpak?: { gpgHomeDir?: string; gpgKeyId: string; }; rpm?: { keyFile: string; keyId?: string; }; }; summary?: string; targets?: ("appimage" | "deb" | "flatpak" | "rpm")[]; urls?: Partial<Record<"bugtracker" | "contact" | "contribute" | "donation" | "faq" | "help" | "translate" | "vcs-browser", string>>; version?: string; }

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

deploy.appimage?

{ compression?: "zstd"; fileName?: string; runtimeFile?: string; updateInformation?: string; }

AppImage packaging options.

deploy.appimage.compression?

"zstd"

Compression explicitly requested from appimagetool.

deploy.appimage.fileName?

string

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

deploy.appimage.runtimeFile?

string

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

deploy.appimage.updateInformation?

string

AppImage update information string embedded in the executable.

deploy.architectures?

("arm64" | "x64")[]

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

deploy.binaryName?

string

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

deploy.branding?

{ dark: string; light: string; }

Primary branding colors included in AppStream metadata.

deploy.branding.dark

string

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

deploy.branding.light

string

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

deploy.categories?

string[]

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

deploy.contentRating?

Record<string, "none" | "intense" | "mild" | "moderate">

OARS 1.1 content-rating attributes mapped to their intensities.

deploy.copyright?

string

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

deploy.deb?

{ compression?: "gzip" | "none" | "xz" | "zstd"; fields?: Record<string, string>; packageName?: string; priority?: string; section?: string; }

Debian package metadata and compression options.

deploy.deb.compression?

"gzip" | "none" | "xz" | "zstd"

Compression used for the Debian package payload.

deploy.deb.fields?

Record<string, string>

Additional Debian control fields, keyed by field name.

deploy.deb.packageName?

string

Debian package name. Defaults to deploy.binaryName.

deploy.deb.priority?

string

Debian package priority. Defaults to optional.

deploy.deb.section?

string

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

deploy.depends?

{ deb?: string[]; rpm?: string[]; }

Additional Debian and RPM dependencies merged with automatically detected dependencies.

deploy.depends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.depends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.description?

string[]

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

deploy.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?

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?

{ email?: string; id?: string; name?: string; }

Developer identity and package maintainer details.

deploy.developer.email?

string

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

deploy.developer.id?

string

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

deploy.developer.name?

string

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

deploy.epoch?

number

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

deploy.execArgs?

string[]

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

deploy.extraFiles?

Record<string, string | DeployExtraFileOptions>

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

deploy.fileAssociations?

object[]

File extensions and MIME types registered for the application.

See

DeployFileAssociationOptions for the fields accepted by each entry.

deploy.flatpak?

{ base?: string; baseVersion?: string; branch?: string; buildCommands?: string[]; cleanup?: string[]; finishArgs?: string[]; lockfile?: string; mode?: "prebuilt" | "source"; modules?: unknown[]; nodeExtension?: string; packageManager?: "npm" | "pnpm" | "yarn"; runtime?: string; runtimeRepo?: string; runtimeVersion?: string; sdk?: string; sdkExtensions?: string[]; shouldEmitBundle?: boolean; shouldInstall?: boolean; shouldUseRofilesFuse?: boolean; source?: { commit?: string; tag?: string; url?: string; }; }

Flatpak runtime, sandbox, build, and distribution options.

deploy.flatpak.base?

string

Optional Flatpak base application ID.

deploy.flatpak.baseVersion?

string

Branch of the base application.

deploy.flatpak.branch?

string

Exported application branch. Defaults to stable.

deploy.flatpak.buildCommands?

string[]

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

deploy.flatpak.cleanup?

string[]

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

deploy.flatpak.finishArgs?

string[]

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

deploy.flatpak.lockfile?

string

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

deploy.flatpak.mode?

"prebuilt" | "source"

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

deploy.flatpak.modules?

unknown[]

Additional Flatpak manifest modules built before the application module.

deploy.flatpak.nodeExtension?

string

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

deploy.flatpak.packageManager?

"npm" | "pnpm" | "yarn"

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

deploy.flatpak.runtime?

string

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

deploy.flatpak.runtimeRepo?

string

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

deploy.flatpak.runtimeVersion?

string

Flatpak runtime branch. Defaults to 50.

deploy.flatpak.sdk?

string

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

deploy.flatpak.sdkExtensions?

string[]

Additional SDK extension IDs included in the build environment.

deploy.flatpak.shouldEmitBundle?

boolean

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

deploy.flatpak.shouldInstall?

boolean

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

deploy.flatpak.shouldUseRofilesFuse?

boolean

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

deploy.flatpak.source?

{ commit?: string; tag?: string; url?: string; }

Git repository and revision used for source builds.

deploy.flatpak.source.commit?

string

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

deploy.flatpak.source.tag?

string

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

deploy.flatpak.source.url?

string

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

deploy.genericName?

string

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

deploy.homepage?

string

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

deploy.isDbusActivatable?

boolean

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

deploy.keywords?

string[]

Search keywords included in the desktop entry and AppStream metadata.

deploy.launcherEnv?

Record<string, string>

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

deploy.license?

string

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

deploy.licenseFile?

string

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

deploy.metadataLicense?

string

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

deploy.metainfoExtra?

string[]

Additional XML fragments appended to the AppStream component.

deploy.mimeTypes?

string[]

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

deploy.minimumLibraryVersions?

Record<string, string>

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

deploy.name?

string

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

deploy.node?

DeployNodeOptions

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

deploy.nodeFlags?

string[]

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

deploy.outDir?

string

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

deploy.protocols?

string[]

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

deploy.relations?

{ breaks?: { deb?: string[]; rpm?: string[]; }; conflicts?: { deb?: string[]; rpm?: string[]; }; preDepends?: { deb?: string[]; rpm?: string[]; }; provides?: { deb?: string[]; rpm?: string[]; }; recommends?: { deb?: string[]; rpm?: string[]; }; replaces?: { deb?: string[]; rpm?: string[]; }; suggests?: { deb?: string[]; rpm?: string[]; }; }

Additional package relationships for Debian and RPM.

deploy.relations.breaks?

{ deb?: string[]; rpm?: string[]; }

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

deploy.relations.breaks.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.breaks.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.conflicts?

{ deb?: string[]; rpm?: string[]; }

Packages that cannot be installed alongside this package.

deploy.relations.conflicts.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.conflicts.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.preDepends?

{ deb?: string[]; rpm?: string[]; }

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

deploy.relations.preDepends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.preDepends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.provides?

{ deb?: string[]; rpm?: string[]; }

Package names or capabilities supplied by this package.

deploy.relations.provides.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.provides.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.recommends?

{ deb?: string[]; rpm?: string[]; }

Recommended packages that extend the application's functionality.

deploy.relations.recommends.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.recommends.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.replaces?

{ deb?: string[]; rpm?: string[]; }

Packages whose files this package may replace.

deploy.relations.replaces.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.replaces.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.relations.suggests?

{ deb?: string[]; rpm?: string[]; }

Suggested companion packages.

deploy.relations.suggests.deb?

string[]

Package relations expressed in Debian dependency syntax.

deploy.relations.suggests.rpm?

string[]

Package relations expressed in RPM dependency syntax.

deploy.release?

string

Debian packaging revision and RPM release. Defaults to 1.

deploy.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?

{ compression?: "gzip" | "xz" | "zstd" | "lzma"; group?: string; packageName?: string; prefixes?: string[]; }

RPM package metadata and compression options.

deploy.rpm.compression?

"gzip" | "xz" | "zstd" | "lzma"

Compression used for the RPM package payload.

deploy.rpm.group?

string

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

deploy.rpm.packageName?

string

RPM package name. Defaults to deploy.binaryName.

deploy.rpm.prefixes?

string[]

Installation prefixes that the RPM package allows users to relocate.

deploy.screenshotBaseUrl?

string

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

deploy.screenshots?

object[]

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

See

DeployScreenshotOptions for the fields accepted by each entry.

deploy.scripts?

{ postInstall?: string; postRemove?: string; preInstall?: string; preRemove?: string; }

Installation and removal scripts for Debian and RPM packages.

deploy.scripts.postInstall?

string

Shell script run after installing a Debian or RPM package.

deploy.scripts.postRemove?

string

Shell script run after removing a Debian or RPM package.

deploy.scripts.preInstall?

string

Shell script run before installing a Debian or RPM package.

deploy.scripts.preRemove?

string

Shell script run before removing a Debian or RPM package.

deploy.signing?

{ appimage?: { gpgKeyId: string; }; deb?: { keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }; flatpak?: { gpgHomeDir?: string; gpgKeyId: string; }; rpm?: { keyFile: string; keyId?: string; }; }

Per-format package signing options.

deploy.signing.appimage?

{ gpgKeyId: string; }

AppImage signing options.

deploy.signing.appimage.gpgKeyId

string

GPG key ID used by appimagetool to sign the AppImage.

deploy.signing.deb?

{ keyFile: string; keyId?: string; method?: "debsign" | "dpkg-sig"; signer?: string; type?: "origin" | "archive" | "maint"; }

Debian package signing options.

deploy.signing.deb.keyFile

string

PGP private key file used to sign the Debian package.

deploy.signing.deb.keyId?

string

PGP signing key ID.

deploy.signing.deb.method?

"debsign" | "dpkg-sig"

Debian package signing method.

deploy.signing.deb.signer?

string

Name and email address recorded as the signer.

deploy.signing.deb.type?

"origin" | "archive" | "maint"

Debian signature role.

deploy.signing.flatpak?

{ gpgHomeDir?: string; gpgKeyId: string; }

Flatpak bundle signing options.

deploy.signing.flatpak.gpgHomeDir?

string

GPG home directory containing the signing key.

deploy.signing.flatpak.gpgKeyId

string

GPG key ID used to sign the Flatpak bundle.

deploy.signing.rpm?

{ keyFile: string; keyId?: string; }

RPM package signing options.

deploy.signing.rpm.keyFile

string

PGP private key file used to sign the RPM package.

deploy.signing.rpm.keyId?

string

PGP signing key ID.

deploy.summary?

string

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

deploy.targets?

("appimage" | "deb" | "flatpak" | "rpm")[]

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

deploy.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?

string

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

deprecations?

{ silence?: never[]; }

Controls warnings for deprecated configuration and behavior.

deprecations.silence?

never[]

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

elements?

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

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

elements.behaviors?

string

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

elements.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?

string[]

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

libraries?

string[]

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

mcp?

{ readOnly?: boolean; tools?: string[]; }

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

mcp.readOnly?

boolean

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

mcp.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?

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.

userEventSignals?

Record<string, string[]>

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

Returns

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.