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.

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 noteworthy features that you won't get with any 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
• A ready-to-deploy GitHub actions pipeline to automatically build end release your application
• Close-to-native theming capabilities with AtlantaFX themes as the basis combined with many manual adjustments
• Advanced error handling and issue tracking with support for Sentry
• Markdown rendering capabilities out-of-the-box with flexmark
• Integrated ability to automatically codesign the application on Windows and macOS
• Solid state management for caches, persistent data, and more
• Many customization options available to users in a comprehensible settings menu
• Update check capabilities for GitHub releases
• Built-in troubleshooting tools for developers and users, including debug mode, heap dump, and more
• Self-restart functionality to spawn new independent processes of your application
• Desktop and registry access support classes
• Plenty of checks to warn users about problems with their system configuration, environment, and compatibility
• Robust dependency management and font handling, your application will even run in WSL
• Hot-reload capabilities for all resources, including reapplying stylesheets
• Application instance management via inter-process communication
• System tray icon support
• Built-in support for Jackson and Lombok
• Built-in translations support with language changes applying instantly

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

It is not particularly 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.