README.md

July 13, 2026 · View on GitHub

Nucleus

The Nucleus framework lets you write cross-platform desktop applications using Kotlin. It is based on Compose Multiplatform and adds native window decorations, deep operating-system integration, code signing, and native installers — all configured through a single Gradle DSL. Your app runs either as a GraalVM Native Image or on the JVM.

Java evolved into Kotlin. JavaScript evolved into TypeScript. Desktop development is going through the same shift: Electron was the pioneer — Kotlin + Compose + Nucleus is what comes next.

Read Why Nucleus for how it compares to Electron and Tauri.

Installation

Nucleus ships as a Gradle plugin. Apply it alongside the Kotlin and Compose plugins in your module's build.gradle.kts:

plugins {
    kotlin("jvm") version "2.4.0"
    id("org.jetbrains.compose") version "1.11.1"
    id("dev.nucleusframework") version "2.0.0"
}

repositories {
    mavenCentral()
    google()
}

dependencies {
    implementation(compose.desktop.currentOs)
    // Entry point — provides nucleusApplication and DecoratedWindow
    implementation("dev.nucleusframework:nucleus.nucleus-application:2.0.0")
    // Tao backend — Rust-native windowing
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:2.0.0")
}

For more installation options, see the install guide and project setup.

Requirements

Nucleus builds on Compose Multiplatform and requires:

Requirement	Version	Note
JDK	17+ (25+ for AOT cache)	JBR 25 recommended
Kotlin	2.0+	Compose Multiplatform requires Kotlin 2.x
Gradle	8.0+	Bundled wrapper is sufficient

Platform support

Each build can compile, run, and package for macOS, Windows, and Linux from a single codebase.

macOS — Intel (x64) and Apple Silicon (arm64), shipped as a universal binary. Liquid Glass on macOS 26.
Windows — x64 and arm64.
Linux — x64 and arm64, with Wayland and X11 support.

Getting started

Create src/main/kotlin/com/example/Main.kt:

package com.example

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        title = "MyApp",
    ) {
        Box(Modifier.fillMaxSize()) {
            Text("Hello from Nucleus")
        }
    }
}

Then configure packaging in build.gradle.kts:

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

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

./gradlew run                              # Run locally in a native Tao window
./gradlew packageDistributionForCurrentOS  # Build an installer for your OS

The full quickstart walks through each step.

Resources for learning Nucleus

nucleusframework.dev/en/docs — all of Nucleus's documentation
Quickstart — build and package your first app
Architecture — the layered model behind the framework
examples/ — demo and sample applications, including the flagship nucleus-demo

What Nucleus provides

Ship everywhere — 18 packaging formats (DMG, PKG, NSIS, MSI, AppX/MSIX, Portable, DEB, RPM, AppImage, Snap, Flatpak, ZIP, TAR, 7Z), store publishing (Mac App Store, Microsoft Store, Snapcraft, Flathub), code signing and notarization, built-in auto-update, deep links, and file associations.

Feel native — Decorated windows with native controls, notifications, taskbar/dock badges and menus, media controls (MPRIS, Now Playing, SMTC), dark mode, accent colors, global hotkeys, and system tray — all behind clean Kotlin APIs.

Perform — GraalVM Native Image compiles your app to a standalone binary (~0.5s cold start, 100–150 MB RAM) with automatic reachability metadata; or run on the JVM with an AOT cache (JDK 25+) and ProGuard-optimized release builds.

Runtime modules

Each module is published independently to Maven Central — use them together or standalone.

Module	Description
`nucleus.core-runtime`	Platform detection, single instance, deep links, executable type
`nucleus.aot-runtime`	AOT cache mode detection
`nucleus.updater-runtime`	Auto-update engine with GitHub/S3, progress tracking, SHA-512
`nucleus.darkmode-detector`	Reactive OS dark mode detection
`nucleus.system-color`	Reactive accent color & high contrast detection
`nucleus.system-info`	CPU, memory, GPU (NVIDIA/AMD/Intel), temperature, network, processes
`nucleus.decorated-window-tao`	Rust-native windowing backend (Tao)
`nucleus.decorated-window-jewel`	Jewel (IntelliJ theme) integration
`nucleus.decorated-window-material2`	Material 2 integration
`nucleus.decorated-window-material3`	Material 3 integration
`nucleus.notification-macos`	macOS User Notifications
`nucleus.notification-windows`	Windows Toast Notifications
`nucleus.notification-linux`	Freedesktop Desktop Notifications
`nucleus.launcher-macos`	macOS Dock API — badge, menus
`nucleus.launcher-windows`	Windows taskbar — badges, jump lists, overlay icons, thumbnail toolbar
`nucleus.launcher-linux`	Unity Launcher — badge, progress, urgency, quicklist
`nucleus.media-control`	OS media controls — MPRIS (Linux), Now Playing (macOS), SMTC (Windows)
`nucleus.menu-macos`	Native macOS menu bar
`nucleus.freedesktop-icons`	Type-safe freedesktop icon naming constants
`nucleus.taskbar-progress`	Cross-platform taskbar progress bar & attention requests
`nucleus.global-hotkey`	System-wide keyboard shortcuts
`nucleus.energy-manager`	Energy efficiency & screen-awake APIs
`nucleus.autolaunch`	Start the app at user login across all platforms
`nucleus.native-ssl`	OS trust store integration
`nucleus.native-http`	HTTP client with native SSL
`nucleus.linux-hidpi`	Native HiDPI scale detection on Linux
`nucleus.graalvm-runtime`	Native-image bootstrap, font fixes, automatic resource inclusion