Skip to content

Nucleus

Nucleus

Gradle Plugin Portal Maven Central Pre Merge Checks License: MIT Kotlin Platform

Nucleus is a toolkit for building production-ready JVM desktop applications on macOS, Windows, and Linux. It combines a Gradle plugin, runtime libraries, and GitHub Actions to tackle the three biggest pain points of desktop JVM development: performance, distribution, and native look & feel.

Compatible with any JVM application, optimized for Compose Desktop.

Why Nucleus?

Performance

  • JDK 25+ AOT cache (Project Leyden) — Dramatically faster cold startup with ahead-of-time class loading cache, enabled as a simple Gradle flag, no GraalVM required

Distribution

  • 16 packaging formats — DMG, PKG, NSIS, MSI, AppX, Portable, DEB, RPM, AppImage, Snap, Flatpak, and archives
  • Plug-and-play store distribution — Store-ready outputs for Mac App Store (PKG), Microsoft Store (AppX), Snapcraft (Snap), and Flathub (Flatpak)
  • Code signing & notarization — Windows (PFX, Azure Trusted Signing) and macOS (Apple Developer ID) with full notarization support
  • Auto-update built-in — Integrated update metadata generation and runtime update library; publish directly to GitHub Releases or S3
  • One DSL — Configure everything from a single nucleus.application { } block

Native Look & Feel

  • Decorated windows — Custom title bar content (icons, text, gradients) while preserving native window controls and behavior on all platforms
  • Reactive dark mode detection — OS-level dark mode listener via JNI (no JNA), triggers recomposition instantly when the user changes their theme
  • Platform-accurate Linux rendering — GNOME Adwaita and KDE Breeze window controls, proper window shape clipping, and focus-aware button states — all drawn with Compose

CI/CD

  • Reusable GitHub Actions — setup-nucleus composite action + workflows for multi-platform matrix builds, universal macOS binaries, and MSIX bundles
  • Deep links & file associations — Cross-platform protocol handlers and file type registration

Quick Example

plugins {
    id("io.github.kdroidfilter.nucleus") version "<version>"
}

nucleus.application {
    mainClass = "com.example.MainKt"

    nativeDistributions {
        targetFormats(TargetFormat.Dmg, TargetFormat.Nsis, TargetFormat.Deb)
        packageName = "MyApp"
        packageVersion = "1.0.0"
    }
}

# Build for current OS
./gradlew packageDistributionForCurrentOS

# Run locally
./gradlew run

Try the Demo

A pre-built demo application is available on the GitHub Releases page. Download the installer for your platform and see Nucleus features in action.

On macOS, install and launch the demo with a single command:

curl -fsSL https://nucleus.kdroidfilter.com/install.sh | bash

This automatically detects your architecture (Apple Silicon or Intel), downloads the latest release, installs it to /Applications, and launches the app.

On Linux (Debian/Ubuntu, Fedora, openSUSE, etc.):

curl -fsSL https://nucleus.kdroidfilter.com/install-linux.sh | bash

This detects your architecture and package manager, then downloads and installs the appropriate .deb or .rpm package.

On Windows, download the appropriate installer from the releases page.

Here's what you'll see:

  • AOT Cache — Near-instant cold startup powered by JDK 25+ ahead-of-time class loading
  • Material Decorated Window — Custom title bar with native window controls, automatically themed with Material 3
  • Dark Mode Detection — Toggle your OS theme and watch the app switch in real time
  • Auto-Update — The app checks for updates on launch, downloads them with progress tracking, and can install & restart in one click

Test auto-update yourself

Download an older release from the releases page, install it, and launch the app. It will detect the newer version, download the update, and offer to install it — all automatically.

The demo source code is in the example/ directory.

Nucleus already supports GraalVM Native Image for instant startup and low memory usage — but configuring reflection metadata remains a major pain point.

I'm looking for sponsors to fund the development of an automatic reflection resolution plugin that would eliminate most of the manual configuration work. This would make native-image practical for large Compose Desktop applications while keeping full compatibility with the Java ecosystem.

If you or your company are interested, please reach out via GitHub Issues or GitHub Discussions. Read more about this in the GraalVM Native Image docs.

Requirements

Requirement Version Note
JDK 17+ (25+ for AOT cache) JBR 25 recommended
Gradle 8.0+
Kotlin 2.0+

License

MIT — See LICENSE.