v2.0.0-beta.1

Read the announcement: GTKX 2.0 beta 1: a smaller, safer foundation.

GTKX 2.0 beta 1 is a prerelease. The final GTKX 2.0 release is scheduled for December 1, 2026, after a three-month migration and hardening period.

Breaking Changes

• The GTKX 1.6 migration behaviors are now standard:
  • GIR byte sequences return Uint8Array instead of number[].
  • Bindings returning GObject.Value return its contents as unknown.
  • Promisified finish methods omit an always-true leading success boolean.
  • Inout records and boxed values mutate the object passed in without repeating it in the return value.
  • Assets use relative ?resource, ?icon, or ?url imports; GSettings schemas use query-free relative imports. The #data/ import map is gone.
  • Gtk-4.0 and Adw-1 are always bound.
  • Generated classes register independently so unused bindings can be tree-shaken.
• Configuration is smaller — Remove the future block from gtkx.config.ts. Graduated flags left at true are temporarily accepted and ignored with a warning; false and unknown flags are configuration errors. Remove retired v2 IDs from deprecations.silence too. libraries now names only dependencies in addition to GTK and Adwaita; libraries: "*" is removed, and explicitly listing Gtk-4.0 or Adw-1 is an error.
• Generated registration follows reachability — A side-effect-only import of a generated namespace no longer retains every class. Import a class when code depends on its registration or resolves it through GObject.typeFromName.
• JSX elements are namespace-only — The bare @gtkx/jsx entry point is removed. Import elements from generated namespace subpaths such as @gtkx/jsx/gtk and @gtkx/jsx/adw; this keeps unrelated generated libraries out of the module graph.
• GTKX is ESM-only on Node.js 26.7 or newer — Published packages expose explicit ESM entry points and reject CommonJS require(). Applications need "type": "module", and Flatpak source builds use the Node 26 SDK extension. (#595, #596)

Removed Deprecated APIs

• addEventListener and removeEventListener on generated GObjects are removed; use on and off.
• Gdk.RGBA.create(css) is removed; construct an RGBA and call parse, checking its result, or provide component values to the constructor.
• Graphene.Point.create, Graphene.Rect.create, and Graphene.Size.create are removed; use their constructors, with Rect.init where appropriate.
• GObject.buildValue is removed; pass the JavaScript value directly or initialize a new GObject.Value.
• The @gtkx/gi/cairo alias is removed; import from @gtkx/cairo.
• Cairo's deprecated *ConstructorProps aliases are removed.
• Property access on animated, such as animated.GtkLabel, is removed; import the component and call animated(GtkLabel).
• AnimatedElements is removed; use AnimatedElementMap. (#595)

Internationalization

• @gtkx/i18n now exposes the upstream i18next and react-i18next APIs instead of maintaining parallel GTKX wrappers and overloads.
• Source extraction uses i18next-cli. Catalog-owning code uses statically recoverable calls under the exact names t, useTranslation, Trans, and TransWithoutContext; imported aliases, member calls such as i18n.t, dynamic keys, and CommonJS declarations are no longer extraction forms.
• Generated declarations augment i18next's standard CustomTypeOptions resources through I18nResources instead of using GTKX's former TranslationRegistry.
• The TranslationRegistry and GTKX-specific TFunction types are removed; use I18nResources and TFunction from i18next.
• Plurals use standard i18next options such as defaultValue_one and defaultValue_other.
• Localized projects require GNU gettext 0.25 or newer. (#596)

Native and Generated Binding Fixes

• Invalid allocation or copy sizes, unregistered GTypes, non-GObject or non-instantiable types, and unknown construction properties now throw JavaScript errors instead of reaching crash-prone native operations.
• GLib criticals raised during an FFI call return through that call instead of aborting the process.
• Generated bindings now classify boxed, fundamental, and plain struct records correctly.
• Plain structs with declared copy and free functions preserve ownership correctly and use their own destructor.
• Marshalling fixes cover arrays and length parameters, callbacks, enums and flags, fundamental and boxed handles, hash tables, strings, GValues, signals, constructors, and virtual methods. (native validation, record ownership, #596)

Toolchain and Release Validation

• Dependencies and build toolchains have been refreshed.
• Flatpak source deployment targets org.freedesktop.Sdk.Extension.node26 and pins pnpm 11.25.
• Generated deployment metadata recognizes additional hosted Git repository URL forms. (toolchain update)
• Release end-to-end validation selects the exact package version being prepared, so prereleases are verified without requiring npm's latest tag.

Full changelog: v1.6.0...v2.0.0-beta.1