# Nucleus > Nucleus is a Kotlin framework for building native cross-platform desktop apps on top of Compose Multiplatform. It combines a Gradle plugin, runtime libraries, and GitHub Actions to handle OS integration (30+ runtime modules), packaging (18 distribution formats), performance (GraalVM Native Image and JVM AOT cache), and native window decorations (Tao backend). - Docs: https://nucleusframework.dev/docs - GitHub: https://github.com/NucleusFramework/Nucleus - Gradle Plugin Portal: https://plugins.gradle.org/plugin/dev.nucleusframework - Maven Central: https://central.sonatype.com/search?q=dev.nucleusframework - License: Apache 2.0 / MIT ## Documentation - [Welcome to Nucleus 2.5](https://nucleusframework.dev/docs): Nucleus is the production desktop layer for Compose Multiplatform — native OS integration and packaging for Kotlin teams. - [Why Nucleus](https://nucleusframework.dev/docs/why-nucleus): What Nucleus adds on top of Compose Multiplatform for Kotlin teams shipping real desktop apps. ### Get started - [Install](https://nucleusframework.dev/docs/start/install): Add the Nucleus Gradle plugin to a Kotlin project to build for macOS, Linux, and Windows from a single build. - [Quickstart](https://nucleusframework.dev/docs/start/quickstart): Build and run your first Nucleus desktop app, then package it as a native installer. - [Project setup](https://nucleusframework.dev/docs/start/project-setup): Configure repositories, the Nucleus plugin, runtime modules, a JDK toolchain, and a multi-module Gradle layout. - [Configuration](https://nucleusframework.dev/docs/start/configuration): Configure the nucleus { } Gradle DSL — application metadata, packaging formats, per-OS options, GraalVM native image, AOT cache, deep links, file associations, and trusted CA injection. ### Concepts - [Architecture](https://nucleusframework.dev/docs/concepts/architecture): The four layers that make up a Nucleus application and how they fit together. - [Runtimes](https://nucleusframework.dev/docs/concepts/runtimes): Nucleus can run your packaged app as a GraalVM native image or on the JVM with an AOT cache, selected from the Gradle build. - [Backends](https://nucleusframework.dev/docs/concepts/backends): Nucleus draws every window through the Tao backend behind the DecoratedWindow API. The legacy AWT backend is deprecated. - [Modules](https://nucleusframework.dev/docs/concepts/modules): How Nucleus splits its runtime into independently versioned Gradle modules and how to add the ones you need. ### Tao backend - [The Tao backend](https://nucleusframework.dev/docs/tao): Tao is a Rust-native window backend that runs Compose Desktop without AWT and adds native Wayland, multi-touch, and pen input. - [DecoratedWindow on Tao](https://nucleusframework.dev/docs/tao/decorated-window): Open a Compose Desktop window on the Tao backend with a custom title bar slot and native window controls, without AWT. - [Window scaffold and chrome](https://nucleusframework.dev/docs/tao/window-scaffold): Build full-window layouts and custom title bars on Tao with WindowScaffold, drag areas, WindowControls, and platform materials. - [Overlay windows](https://nucleusframework.dev/docs/tao/overlay-windows): Build watermarks, desktop widgets, and heads-up overlays with transparent, click-through, always-on-bottom, and all-workspaces windows on the Tao backend. - [Native views on Tao](https://nucleusframework.dev/docs/tao/native-views): Embed any platform-native view — NSView, HWND, or GtkWidget — inside a Compose layout on the Tao backend. - [TextureView](https://nucleusframework.dev/docs/tao/texture-view): Composite an externally produced GPU texture into the Compose scene on the Tao backend without a CPU frame copy. - [GPU render context](https://nucleusframework.dev/docs/tao/gpu-render-context): Give in-process GPU renderers the scene's Skia DirectContext and native device so they can composite without a second GPU or per-frame copy. - [Multi-touch & gestures](https://nucleusframework.dev/docs/tao/multi-touch): Read trackpad and touch gestures on the Tao backend through Compose pointer events, or the raw gesture stream. - [Pen & stylus input](https://nucleusframework.dev/docs/tao/pen-stylus): Read pen and touchscreen pressure from Compose pointer events on the Tao backend. - [Drag and drop](https://nucleusframework.dev/docs/tao/drag-and-drop): Receive dropped files on the Tao backend through the standard Compose dragAndDropTarget API. - [Accessibility](https://nucleusframework.dev/docs/tao/accessibility): The Tao accessibility bridge projects your Compose semantics tree onto the native accessibility API of each operating system. - [Native Wayland](https://nucleusframework.dev/docs/tao/wayland): The Tao backend renders Compose Desktop apps directly on Wayland and falls back to X11 automatically. - [Per-monitor HiDPI](https://nucleusframework.dev/docs/tao/hidpi): The Tao backend tracks a per-window scale factor so Compose layouts stay in Dp while rendering matches each display's pixel density. - [Taskbar progress](https://nucleusframework.dev/docs/tao/taskbar-progress): Show determinate, indeterminate, and error progress on the taskbar or dock from a Tao window. - [Migrate from JBR to Tao](https://nucleusframework.dev/docs/tao/migration-from-jbr): Switch an existing Nucleus app from the AWT backend to the Tao backend and retest the platform integrations that change. ### Window & toolkits - [Window & toolkits](https://nucleusframework.dev/docs/window): How Nucleus opens native desktop windows from Compose through the DecoratedWindow composable, the TitleBar slot, and the toolkit modules that restyle them. - [Native design systems](https://nucleusframework.dev/docs/window/toolkits): macOS 26, Fluent, Yaru, Jewel and Material restyle the same Nucleus window for each desktop design language. - [Context menus](https://nucleusframework.dev/docs/window/context-menu): Replace Compose-drawn context menus with the OS-looking menu — NSMenu on macOS, a Fluent flyout on Windows, and Adwaita or Breeze on Linux. - [macOS 26 design system](https://nucleusframework.dev/docs/window/toolkit-macos): Compose Multiplatform macOS 26 UI with Liquid Glass materials and a Nucleus-backed decorated window. - [Fluent design system](https://nucleusframework.dev/docs/window/toolkit-fluent): Windows 11 Fluent UI for Compose Multiplatform, with a Nucleus-backed FluentDecoratedWindow. - [Yaru design system](https://nucleusframework.dev/docs/window/toolkit-yaru): Ubuntu Yaru widgets and themes for Compose Multiplatform, with a Nucleus-backed YaruDecoratedWindow. - [Jewel — IntelliJ Platform](https://nucleusframework.dev/docs/window/toolkit-jewel): Style a DecoratedWindow with Jewel colors and metrics so the title bar and chrome match the IntelliJ Platform look. - [Material 2 & Material 3](https://nucleusframework.dev/docs/window/toolkit-material): Theme a Nucleus DecoratedWindow from a Compose MaterialTheme, using either the Material 2 or Material 3 adapter. ### PDF reader - [PDF reader](https://nucleusframework.dev/docs/pdf): Render PDFs, extract text, and select or copy content from Compose, with one API across Android, iOS, web, and desktop. - [Getting started](https://nucleusframework.dev/docs/pdf/getting-started): Load PDF bytes, react to loading state, and enable text selection, links, thumbnails, and zoom. - [API reference](https://nucleusframework.dev/docs/pdf/api-reference): PdfReaderState, PdfPage, PdfThumbnail, PdfReader, and the supporting data types. ### WebView - [WebView](https://nucleusframework.dev/docs/webview): Embed a native web engine in Compose with one API across Android, iOS, web, and desktop. - [Getting started](https://nucleusframework.dev/docs/webview/getting-started): Load URLs and HTML, navigate the history stack, evaluate JavaScript, and intercept requests from Compose. - [API reference](https://nucleusframework.dev/docs/webview/api-reference): WebView, WebViewState, WebViewNavigator, settings, cookies, JS bridge, and request interception. ### OS integration - [OS integration](https://nucleusframework.dev/docs/os): Kotlin modules that expose native macOS, Windows, and Linux desktop capabilities such as notifications, system tray, global hotkeys, media controls, dark mode, and system colors. - [Cross-platform notifications](https://nucleusframework.dev/docs/os/notifications): Send desktop notifications on macOS, Windows, and Linux from a single Kotlin API. - [Notifications on macOS](https://nucleusframework.dev/docs/os/notification-macos): Kotlin bindings for Apple's UserNotifications framework, covering authorization, categories, attachments, text input, schedules, and interruption levels. - [Notifications on Windows](https://nucleusframework.dev/docs/os/notification-windows): Send Windows toast notifications from Kotlin with adaptive layouts, images, buttons, text input, and progress bars. - [Notifications on Linux](https://nucleusframework.dev/docs/os/notification-linux): Send freedesktop desktop notifications over D-Bus from Kotlin, with urgency, hints, sounds, and action callbacks. - [System tray](https://nucleusframework.dev/docs/os/system-tray): Render a tray icon and a native context menu from Compose on macOS, Windows, and Linux. - [Tray menu DSL](https://nucleusframework.dev/docs/os/tray-menu-dsl): Build the tray context menu from Kotlin with items, checkable items, submenus, dividers, and conditional content. - [Tray-anchored apps](https://nucleusframework.dev/docs/os/tray-app): TrayApp anchors a Compose popup window to a system tray icon so you can build menu bar apps in Kotlin. - [Global hotkeys](https://nucleusframework.dev/docs/os/global-hotkey): Register OS-wide keyboard shortcuts that fire even when your app does not have focus. - [Media controls](https://nucleusframework.dev/docs/os/media-control): Publish now-playing metadata to the system media center and handle playback commands on macOS, Windows, and Linux from Kotlin. - [Dark mode detector](https://nucleusframework.dev/docs/os/dark-mode): Detect the operating system's dark mode from Kotlin and recompose your Compose UI when the theme changes. - [System accent colour](https://nucleusframework.dev/docs/os/system-color): Read the user's OS accent colour and high-contrast setting as reactive Compose state. - [System info](https://nucleusframework.dev/docs/os/system-info): Read host details — OS, CPU, memory, disks, GPUs, batteries, network, processes, and users — through the SystemInfo object. - [macOS menu bar](https://nucleusframework.dev/docs/os/menu-macos): Build the native macOS menu bar from Compose, with items, keyboard shortcuts, icons, badges, and submenus that react to state. - [Spell check](https://nucleusframework.dev/docs/os/spell-check): Check spelling in Compose text fields through each operating system's native engine — Hunspell on Linux, NSSpellChecker on macOS, and the Windows Spell Checking API. - [SF Symbols](https://nucleusframework.dev/docs/os/sf-symbols): Type-safe Kotlin constants for Apple SF Symbol names used by macOS APIs. - [FreeDesktop icon names](https://nucleusframework.dev/docs/os/freedesktop-icons): Typed Kotlin constants for the names defined by the FreeDesktop Icon Naming Specification. ### Lifecycle - [App lifecycle, from cold launch to sleep](https://nucleusframework.dev/docs/lifecycle): The lifecycle modules connect a Nucleus app to the OS events and services that outlive any single window. - [One app, one process](https://nucleusframework.dev/docs/lifecycle/single-instance): Enforce a single running instance of your app and forward a second launch's arguments to the primary process. - [Deep links and URL schemes](https://nucleusframework.dev/docs/lifecycle/deep-links): Register a custom URL scheme at packaging time and receive the incoming deep-link URI in your Nucleus app at runtime. - [App metadata at runtime](https://nucleusframework.dev/docs/lifecycle/app-metadata): Read your app's id, version, vendor, display name, and Windows AUMID from Kotlin at runtime. - [How was I launched?](https://nucleusframework.dev/docs/lifecycle/executable-type): Detect at runtime how the app was packaged and launched, from a DMG or Snap to a plain ./gradlew run. - [Launcher (macOS)](https://nucleusframework.dev/docs/lifecycle/launcher-macos): Populate the Dock right-click menu of a macOS app with items, submenus, and separators, and handle clicks from Kotlin. - [Launcher (Windows)](https://nucleusframework.dev/docs/lifecycle/launcher-windows): Drive the Windows taskbar from Kotlin with overlay icons, jump lists, thumbnail toolbar buttons, and badges. - [Launcher (Linux)](https://nucleusframework.dev/docs/lifecycle/launcher-linux): Set count badges, progress bars, urgency flags, and right-click quicklist menus on the Linux launcher from Kotlin. - [Launch at login](https://nucleusframework.dev/docs/lifecycle/auto-launch): Enable, disable, and query start-at-login from Kotlin with a single API that resolves the backend for the current packaging format. - [Scheduler — cron jobs that survive reboots](https://nucleusframework.dev/docs/lifecycle/scheduler): Run periodic, calendar, and on-boot background tasks from Kotlin that the OS fires on schedule even when your app is closed. - [Scheduler testing](https://nucleusframework.dev/docs/lifecycle/scheduler-testing): Test doubles for the scheduler that run background tasks in memory, with virtual time and controllable constraints. - [Service Management (macOS)](https://nucleusframework.dev/docs/lifecycle/service-management): Register login items, launch agents, and launch daemons through the macOS SMAppService API from Kotlin. - [Energy manager](https://nucleusframework.dev/docs/lifecycle/energy-manager): Lower your app's OS scheduling priority and keep the display awake from Kotlin. - [Taskbar progress](https://nucleusframework.dev/docs/lifecycle/taskbar-progress): Draw progress bars and attention requests on the dock, taskbar button, or Unity launcher entry from Kotlin. - [Filesystem watcher](https://nucleusframework.dev/docs/lifecycle/fs-watcher): Watch files and directories for changes from Kotlin and receive create, modify, remove, and move events as a coroutine Flow. ### Performance & native - [Performance and native runtimes](https://nucleusframework.dev/docs/performance): Nucleus builds the same Kotlin source into two runtimes — a GraalVM native image or a JDK 25 image with an AOT cache — selected from one Gradle DSL. - [Benchmarks](https://nucleusframework.dev/docs/performance/benchmarks): Measured cross-runtime benchmark results — one Geekbench-style suite run inside a real Compose desktop app across JVM JIT, GraalVM Native Image, SwiftUI, Tauri, and Flutter. #### GraalVM Native Image - [GraalVM Native Image](https://nucleusframework.dev/docs/performance/graalvm): GraalVM Native Image compiles a Nucleus app ahead of time into a self-contained native binary, with reflection, resource, and JNI metadata generated for every Nucleus module. - [Configuration](https://nucleusframework.dev/docs/performance/graalvm/configuration): Reference for the graalvm { } DSL block that configures GraalVM native-image builds, including toolchain, image name, build arguments, metadata repository, and per-OS settings. - [Automatic metadata resolution](https://nucleusframework.dev/docs/performance/graalvm/automatic-metadata): How Nucleus resolves and merges GraalVM reachability metadata at build time so native images compile without hand-written configuration. - [Tasks & CI](https://nucleusframework.dev/docs/performance/graalvm/tasks-ci): The Gradle tasks the Nucleus plugin adds for GraalVM native image, where their output lands, and how to run them on each OS in CI. - [AOT cache](https://nucleusframework.dev/docs/performance/aot-cache): Generate a Project Leyden AOT cache at build time and bundle it with your installer to skip JVM warmup at launch. - [Native access — reflection metadata, resolved for you](https://nucleusframework.dev/docs/performance/native-access): Nucleus generates the reflection, resource, and JNI metadata a GraalVM Native Image build needs, merging it from several sources so the build compiles without hand-written JSON. - [Native code in Kotlin](https://nucleusframework.dev/docs/performance/native-code): Write the native side in Kotlin/Native and call it from the JVM as a plain Kotlin API. NucleusNativeAccess generates the FFM bridge, the JVM proxies, and the GraalVM metadata for you. - [Native library loader](https://nucleusframework.dev/docs/performance/native-library-loader): How Nucleus loads JNI shared libraries from the module JARs — system path first, then a content-addressed cache under the OS cache directory. - [Native HTTP — the OS trust store, pre-wired](https://nucleusframework.dev/docs/performance/native-http): Preconfigure java.net.http.HttpClient, OkHttp, or Ktor with the operating system trust store through NativeTrustManager. - [Native SSL](https://nucleusframework.dev/docs/performance/native-ssl): Read trusted certificates from the operating system store and merge them with the JVM defaults into a single trust manager. ### Packaging & distribution - [One DSL, eighteen installers](https://nucleusframework.dev/docs/packaging): Declare the desktop distribution formats you need in the Gradle plugin's DSL and build each one the host operating system supports. - [Building for macOS](https://nucleusframework.dev/docs/packaging/macos): Package a Nucleus app for macOS as a DMG or a Mac App Store PKG, then sign and notarize the build. - [Building for Windows](https://nucleusframework.dev/docs/packaging/windows): Package a Nucleus app for Windows as an NSIS, MSI, MSIX/AppX, or Portable build and sign it for distribution. - [Building for Linux](https://nucleusframework.dev/docs/packaging/linux): Configure a Nucleus app to build DEB, RPM, AppImage, and pacman packages and publish to the Snap and Flatpak stores. - [Code signing](https://nucleusframework.dev/docs/packaging/code-signing): Sign and notarize your app's installers on macOS, sign with a PFX certificate or Azure Artifact Signing on Windows, and GPG-sign DEB/RPM packages on Linux. - [Trusted CA certificates](https://nucleusframework.dev/docs/packaging/trusted-certificates): Import private root CA certificates into the JDK bundled with your packaged app so its HTTPS calls trust them. - [Sandboxing](https://nucleusframework.dev/docs/packaging/sandboxing): How Nucleus builds sandboxed distributions for the App Store, Flatpak, and MSIX store formats. - [Auto-update](https://nucleusframework.dev/docs/packaging/auto-update): Check for, download, verify, and install application updates from Kotlin, without a third-party service. - [Publishing](https://nucleusframework.dev/docs/packaging/publishing): Configure Nucleus to publish signed installers and auto-update metadata to GitHub Releases, S3, or a generic HTTP host. - [CI/CD](https://nucleusframework.dev/docs/packaging/ci-cd): Build, sign, and publish a Nucleus desktop app across macOS, Windows, and Linux with the composite GitHub Actions shipped in the Nucleus repository. ### Compare - [Compare](https://nucleusframework.dev/docs/compare): How Nucleus compares with vanilla Compose Multiplatform — and, secondarily, with other desktop stacks. - [Nucleus vs vanilla Compose Multiplatform](https://nucleusframework.dev/docs/compare/cmp-default): What Nucleus adds on top of JetBrains Compose Desktop — the decision table for Kotlin teams shipping production desktop apps. - [Packaging — Nucleus vs the rest](https://nucleusframework.dev/docs/compare/packaging): How Nucleus compares with jpackage, Compose Multiplatform, Conveyor, install4j, and other JVM packaging tools across formats, auto-update, signing, CI, and store distribution. ### Ecosystem - [Thirty years of mature libraries, native to your app](https://nucleusframework.dev/docs/ecosystem): Nucleus apps run on the JVM, so any library on Maven Central is a Gradle dependency away; this page groups the common desktop choices by task. - [Native file dialogs](https://nucleusframework.dev/docs/ecosystem/file-dialog): Use FileKit for native open, save, and folder pickers, with GraalVM metadata bundled by the Nucleus plugin. ### Migrate - [Migrate with an AI agent](https://nucleusframework.dev/docs/migrate/ai-agent): Point any AI coding agent at one URL and it analyzes your app, asks the right questions, and migrates it to Nucleus step by step. - [Migrating from JetBrains Compose Desktop](https://nucleusframework.dev/docs/migrate/from-jb-compose): Add Nucleus to an existing JetBrains Compose Desktop project and move its build configuration to the Nucleus DSL. - [Migrating from Nucleus 1.x to 2.0](https://nucleusframework.dev/docs/migrate/from-1.x): Port a Nucleus 1.x desktop app to 2.0 by renaming the project namespace and moving bootstrap into nucleusApplication. ### Reference - [Gradle DSL reference](https://nucleusframework.dev/docs/reference/gradle-dsl): Every property and sub-block of the nucleus { } Gradle extension, verified against the plugin source. - [Troubleshooting](https://nucleusframework.dev/docs/reference/troubleshooting): Common build, packaging, signing, and runtime problems in Nucleus, with the cause and fix for each. - [Roadmap](https://nucleusframework.dev/docs/roadmap): What shipped in Nucleus 2.0–2.5, the modules planned next, and features under consideration. - [Changelog](https://nucleusframework.dev/docs/changelog): Release notes for every Nucleus release, newest first. ## Full documentation - [llms-full.txt](https://nucleusframework.dev/llms-full.txt): the complete documentation in a single file