Introduction

About

KickstartFX is a ready-to-use template for JavaFX applications. You can just clone it, install the few required tools to build it, and then run it. It can serve as a solid foundation for your own JavaFX application as everything is fully customizable and extendable.

You can find the repository at https://github.com/xpipe-io/kickstartfx.

KickstartFX is more than just a basic template that opens a simple window. It contains a lot of code to handle the challenges of applications in the real world to achieve the best possible desktop application experience across all operating systems. The code is based on XPipe, a well-established JavaFX application, and is the result of years of experience developing a desktop application that is used by many thousands of users right now.

It features the following features that you won't find in other templates:

• A fully up-to-date build using the latest features of JDK25, Gradle 9, JavaFX 25, WiX 6, and much more
• Native executable and installer generation for all operating systems using native tools
• A fully modularized build, including fully modularized dependencies and the usage of jmods
• Leyden AOT cache generation logic and customizable training run implementations
• A ready-to-deploy GitHub actions pipeline to automatically build and release your application on all platforms
• Close-to-native theming capabilities with AtlantaFX themes as the basis combined with many manual improvements
• Advanced error handling and issue tracking with built-in support for Sentry
• Markdown rendering capabilities out-of-the-box with flexmark and the JavaFX WebView
• Integrated ability to automatically codesign the application on Windows and macOS
• Solid state management for caches, persistent data, and more
• Many common customization options available to users in a comprehensible settings menu
• Update check capabilities and notifications for new GitHub releases
• Built-in troubleshooting tools for developers and users, including debug mode, heap dump, and more
• Hot-reload capabilities for all resources, including reapplying stylesheets
• Plenty of checks to warn users about problems with their system configuration, environment, and compatibility
• Desktop and registry access support classes
• Robust dependency Linux package management and font handling, your application will even run in WSL
• Application instance management and coordination via inter-process communication
• System tray icon support and proper handling of AWT/Swing alongside JavaFX
• Built-in support for Jackson and Lombok
• Integrated translation support with user interface language changes applying instantly
• Self-restart functionality to spawn new independent processes of your application
• Application logo templates that look native on every operating system, including a macOS 26 liquid glass icon
• Included third-party open source licenses of all dependencies, plus the required button to display them in the application

You can run the latest release right now to see for yourself. These releases were generated using this template repository.

This project is not focused on handholding, meaning that you will not find step-by-step instructions for everything. Big-picture concepts and noteworthy parts are covered in the documentation, but not every small detail is explained or documented. It is intended that you spend some time discovering the codebase for yourself as ideally you might be working with it in the future if you decide to build your application with it. Going through the code and understanding the idea behind it is important, and this is much easier if you have already some experience with JavaFX. If you have never built an application with Java/JavaFX, there will be a steep learning curve when figuring out how everything works.

Fully up-to-date

KickstartFX focuses on utilizing the latest features and tools. It uses the latest features in JDK25 and the latest tools for package generation. You will, for example, not find other templates that have fully-integrated JDK25 project Leyden AOT optimizations, use the JavaFX 22 platform preferences extensively, and come with a WiX v6 installer generation script. All being tied together with gradle 9 build scripts.

Native feel

A common case with JavaFX applications is that they stand out when running side-by-side with native applications. The colors, the fonts, the colors, or the window frame might look off for users, which does not leave a good first impression. The goal of KickstartFX is that your application looks and behaves almost identical to a native application, so that the average user might not be even able to tell which one is not native.

To accomplish this, KickstartFX uses a robust stylesheet system based on top of AtlantaFX. It follows the light/dark mode of the system, adapts the accent color on your system accent color, improves the window frame, adjusts fonts, and more to deliver a close-to-native experience.

Native tools

In contrast to many other existing JavaFX template projects, KickstartFX does not rely on any opinionated or niche all-in-one solution to somehow generate packages and installers for all operating systems. Instead, it is carefully crafted to create the packages using native tools on each operating system, orchestrated by gradle build scripts. It comes with the ability to generate installers for all operating systems using native tools to create .msi, .deb, .rpm, and .pkg installers. Furthermore, it also generates .dmg, .zip, and .tar.gz portables. The entire build workflow can be fully customized, using the existing scripts as a basis.

GitHub actions workflow included

The project comes with GitHub actions workflows to automatically build and sign your application on all available platforms and create a new GitHub release with them. They also contain code you can enable to build on custom platforms which are not supported by the normal hosted runners yet, e.g. Windows ARM or Linux ARM platforms. The workflows are state-of-the-art and can easily be expanded to customize your distribution workflow.

Ready to be signed

The goal of KickstartFX is that you can build applications without much hassle that work in production and provide a smooth user experience. A part of this experience is signing the code on various operating systems. Nowadays, if you distribute unsigned code, your users will either receive scary warnings or errors when running your application. KickstartFX comes with full integrated capabilities to codesign your application and packages on Windows and macOS. The only thing you need is to set up your signing infrastructure based on the instructions you can find these docs and configure certain environment variables for the build. Once that is done, the build will automatically produce signed artifact completely automatically.

Built the right way

The current state application development with Java and JavaFX is quite sad. You will find that many people struggle with properly setting up the build so that they can generate native executables with a bundled JDK, because it's not a trivial process and requires some knowledge. As a result, many external tools popped up that promise and easier workflow to generate packages to distribute. These tools come with their own problems and limitations, so some people are disappointed after trying multiple tools.

There is only one intended way to properly create native application images, and that is true using jlink/jpackage on a fully-modularized project. Anything else, especially not using modularity and instead using fat jars / shaded jars, is a bad solution and will cause you problems at some point. Using any kind of external tools is also not the right way, you will just have to deal with other kinds of problems and limitations instead.

KickstartFX is fully modular, and can therefore easily generate working runtime images. It comes with the tools to convert any non-modular dependencies into proper modules using the extra-java-module-info gradle plugin, without much hassle. It also comes with proper jmod support to avoid the need for dynamic library extraction in the temporary directory. All included dynamic libraries, the ones of JavaFX and JNA by default, are included in the generated runtime image via jmods. This improves startup speed and error-resistance, just by using modules properly.

Runs everywhere

The application runs on:

• Windows 7+
• macOS 10.11+
• Linux

Special care is taken for many more exotic Linux variants so that the application will still run. The Linux installers declare all necessary dependency packages for JavaFX, allowing you to install it even in systems like WSL and have your application run successfully.

Status

KickstartFX is a brand-new project, at least technically. While most parts come straight from XPipe, there was still some work done adapting the code and build scripts to be more template-friendly in this new repository. While the original codebase from XPipe is very stable, there might be issues that were introduced in the template creation process when adapting the original codebase. These should be ironed out in a while. Make sure to report any issues that you find.

Projects using KickstartFX

As this project is brand-new, there are only two projects that are based on KickstartFX. You can take a look at them for inspiration on what you can implement with KickstartFX as the basis:

• XPipe: The XPipe project can show you what a fully customized project can look like. While KickstartFX is based on XPipe, going the other way around can show you what is possible with KickstartFX and JavaFX in general. If you are looking to evaluate whether the JavaFX tech stack is a suitable and future-proof solution for your planned desktop application, make sure to give XPipe a try.

• Pdx-Unlimiter: The Pdx-Unlimiter project is an older JavaFX-based companion app for various strategy games. It has a large community in gaming and has been developed over the last 5 years. With the release of KickstartFX, the whole application was reworked to be based on KickstartFX, throwing out all the old legacy JavaFX platform code. The v3 releases, which are currently in beta, come with a completely redesigned interface and a much improved user experience. Plus a lot of performance improvements automatically included with KickstartFX.

If you are building a project with KickstartFX, let us know and your project can be added to this list.