Nucleus vs vanilla Compose Multiplatform

Nucleus is a superset of the JetBrains org.jetbrains.compose Desktop packaging plugin. It keeps the same DSL shape and Gradle tasks, and adds a wider format catalog, packaging for store channels, and runtime libraries the official plugin does not ship. If you already have a Compose Multiplatform desktop project, migration is a drop-in.

What's the same

Migrating preserves your mainClass, nativeDistributions { … }, buildTypes, modules, and every existing Gradle task.

What Nucleus adds

Format catalog

Eighteen formats against six. The plugin uses jpackage to build the app-image, then hands it to electron-builder's --prepackaged mode for everything else.

Store pipeline

PKG, AppX, and Flatpak trigger a parallel sandboxed pipeline that pre-extracts JNI libs, signs each .dylib, injects sandbox-aware JVM args, and applies the right entitlements. The default CMP plugin has no notion of this.

Auto-update

updater-runtime ships latest-*.yml metadata and a Kotlin client compatible with electron-builder's update format. See auto-update.

GraalVM Native Image

The plugin can compile your Compose Desktop app to a GraalVM Native Image and package the resulting binary as DMG, NSIS, or DEB. Cold start is around 0.2 s and RAM around 30 MB (measured on Windows 11 with a Hello World build). The default CMP plugin does not handle Native Image.

AOT cache

The JDK 25+ AOT cache is wired through the enableAotCache = true flag, with training and runtime modes detected via nucleus.aot.mode. See AOT cache.

Code signing

Nucleus extends signing to Windows (PFX or Azure Artifact Signing) and adds the macOS inside-out signing pipeline for universal binaries via the build-macos-universal CI action.

Deep links and file associations

protocol("MyApp", "myapp") and fileAssociation(...) propagate to NSIS, MSI, AppX, DEB/RPM .desktop files, and the macOS Info.plist. The default CMP plugin requires per-OS configuration.

Runtime libraries

None of these ship with vanilla CMP:

• core-runtime — NucleusApp, DeepLinkHandler, SingleInstanceManager, ExecutableRuntime.
• nucleus-application — the nucleusApplication { } umbrella entry point, automatic single-instance, deep-link delivery, GraalVM init.
• Decorated windows — Liquid Glass / Fluent / Yaru / Jewel, on the Tao backend.
• OS toolkits — notifications, system tray, global hotkeys, media controls, taskbar progress, energy manager, system info, scheduler, autolaunch, native SSL, native HTTP, and more.

What stays unchanged

• mainClass, jvmArgs, modules() / includeAllModules.
• buildTypes / ProGuard.
• The compose.desktop.currentOs dependency.
• Existing Gradle tasks (run, packageDmg, packageDeb, …).
• Existing Gradle tasks and DSL carry over unchanged. (Note: Compose Hot Reload is not supported in Nucleus 2.0 — hotRun / hotDev were added in 2.1.)

Set homepage for DEB packages

Unlike jpackage, electron-builder requires homepage for DEB. Set it on nativeDistributions:

nativeDistributions {
    homepage = "https://myapp.example.com"
}

When to stay on vanilla CMP

• You only need DMG/MSI/DEB and you're satisfied with jpackage as the back end.
• You don't need auto-update, GraalVM, store distribution, or native window decorations.
• Your build pipeline already has bespoke signing and upload scripts you don't want to displace.

When to switch to Nucleus

• You want packaging for store channels (Mac App Store PKG, Microsoft Store MSIX, Snapcraft, Flathub).
• You want auto-update or GraalVM Native Image.
• You want native window decorations with the Tao backend's multi-touch, pen, and native Wayland support.
• You want the 40+ OS integration modules without building them yourself.

What's next

• Migrating from JetBrains Compose Desktop — the step-by-step migration.
• Sandboxing — the store distribution pipeline.
• Auto-update — updater metadata and the Kotlin client.
• AOT cache — JDK 25+ AOT cache wiring.