Deploying JavaFX Applications


2 Getting Started

This page shows you the basics of taking your JavaFX application from code to deployment.

2.1 Deployment Quick Start

Mastered JavaFX basics and have your application ready? Now want to learn what to do to publish it?

Here is all you have to do:

  • Decide how you want to deploy the application.

  • Use JavaFX tools to create the application package.

  • If you plan to embed the application in a web page, update your HTML page to include the generated JavaScript snippet.

  • Copy the package to the place you want to deploy it.

  • You are done.

If you would like to try these steps in packaging one of the tutorial applications in the JavaFX Getting Started series using the NetBeans IDE, see the page on basic deployment and try out any of the tutorials.

2.2 Write Once, Deploy Anywhere

The same JavaFX application can be used in multiple execution environments including:

  • Launching a desktop application

  • Launching from the command line using the Java launcher

  • Launching by clicking a link in the browser to download an application

  • Viewing in a web page when opened

2.3 Application Package

By default, all of the JavaFX packaging tools generate the following collection of files needed to run the application:

  • An application JAR file (or multiple JAR files for large applications)

  • A JNLP file with a deployment descriptor

    A deployment descriptor is an XML file that describes application components, platform requirements, and launch rules.

  • An HTML file containing JavaScript code to embed or launch JavaFX content from the web page

For the Colorful Circles application from the JavaFX Getting Started tutorials, the basic package consists of these files:

  • ColorfulCircles.jar

  • ColorfulCircles.jnlp

  • ColorfulCircles.html

2.3.1 Self-Contained Applications

Starting from JDK 7 update 6, JavaFX applications can be packaged as a platform-specific, self-contained application. These applications include all application resources, the Java and JavaFX runtimes, and a launcher, and they provide the same install and launch experience as native applications for the operating system.

Self-contained applications can be distributed as zip files or as installable packages: EXE or MSI for Windows, DMG for Mac, or RPM or DEB for Linux.

Depending on your requirements, this may be a good distribution vehicle for your application:

  • They resemble native applications for the target platform, in that users install the application with an installer that is familiar to them and launch it in the usual way.

  • They offer no-hassle compatibility. The version of Java Runtime used by the application is fully controlled by the application developer.

  • Your application is easily deployed on fresh systems with no requirement for Java Runtime to be installed.

  • Deployment occurs with no need for admin permissions when using ZIP or user-level installers.

For more information, see Chapter 6, "Self-Contained Application Packaging."

2.4 Packaging Tools

There are three different tools that you can use to package your application:

The HTML page generated by default is a simple test page for your application. It includes sample JavaScript code to launch and embed your application, which you can copy to your own web page. To avoid manual copying, consider using HTML templates for application packaging to insert these code snippets into an existing web page. For more information, see Section 5.7.4, "Web Page Templates."

For more information about JavaFX packaging, see Chapter 5, "Packaging Basics."

2.4.1 NetBeans IDE

If you use Netbeans IDE (see the JavaFX Getting Started tutorials for information about how to use JavaFX projects in Netbeans IDE), then it will do most of the work for you. Open Project Properties to specify preferred dimensions for your application scene. Enter 800 for width and 600 for height if you use the Colorful Circles example. Then build the project with Clean and Build. Your application package is generated to the dist folder. Open it in Windows Explorer and try double-clicking the HTML, JNLP, or JAR files.

For more information about packaging and deploying simple JavaFX applications using NetBeans IDE, see the basic deployment page in the Getting Started with JavaFX tutorials.

If you want to package a self-contained application, you need to customize the build.xml script in the NetBeans IDE. For more information, see Section 6.3.2, "Basic Build."

2.4.2 Ant Tasks

If you are using another IDE, then you can add JavaFX packaging as a post-build step, using Ant tasks that are included in the JavaFX SDK. Example 2-1 shows an Ant package task for Colorful Circles.

When you add the attribute nativeBundles="all" attribute into the <fx:deploy> Ant task, all possible packages will be created: a standalone application package, one or more self-contained application packages for that platform, and a web deployment package. Installable packages are created based on the third-party software that is available at packaging time. For example, if you have both Inno Setup and WiX on Windows, then you will get three packages: a folder with the application, an .exe installer file, and an .msi installer file. For more information, see Chapter 5, "Packaging Basics." A simple Ant task with the nativeBundles attribute is shown in Example 2-1.

Example 2-1 Ant Task to Produce All Packages for the ColorfulCircles Application

<taskdef resource="com/sun/javafx/tools/ant/antlib.xml"      
<fx:jar destfile="dist-web/ColorfulCircles.jar">
    <fx:application mainClass="colorfulcircles.ColorfulCircles"/>
    <fileset dir="build/classes/">
        <include name="**"/>
<fx:deploy width="800" height="600" outdir="dist-web" 
        outfile="ColorfulCircles" nativeBundles="all">
    <fx:info title="Colorful Circles"/>
    <fx:application name="Colorful Circles example"
        <fx:fileset dir="dist-web" includes="ColorfulCircles.jar"/>


2.4.3 JavaFX Packager Command-Line Tool

If you cannot use Ant and prefer command-line tools, use the JavaFX Packager tool that comes with the JavaFX SDK. The JavaFX Packager tool has several commands for packaging applications, described in Chapter 11, "The JavaFX Packager Tool." For a quick test build, you can use the javafxpackager -makeall command, such as the one in Example 2-2. This command compiles source code and combines the javafxpackager -createjar and javafxpackager -deploy commands, with simplified options.

Example 2-2 javafxpackager -makeall Command to Build an Application

javafxpackager -makeall -appclass colorfulcircles.ColorfulCircles 
    -name "Colorful Circles" -width 800 -height 600

As a command intended only to help to build simple projects quickly, the -makeall command supports a limited set of options to customize the command behavior. The -makeall command makes the following assumptions about input and output files:

  • Source and other resource files must be in a directory named src under the main project directory.

  • The resulting package is always generated to a directory named dist, and file names all start with the dist prefix.

  • By default, the -makeall command tries to build a self-contained application package. If this is not possible, the JAR, HTML, and JNLP files are generated so you can deploy to any other execution mode.


Stage width and height must always be specified for applications embedded in the browser.

When your application is ready to go live, use the -createjar and -deploy commands instead of the -makeall command. The -createjar and -deploy commands have considerably more options. You can create a self-contained application package with the -deploy command plus the -native option. For more information, see Section 5.3.1, "JavaFX Packaging Tools."


For even more flexibility of options, use an Ant task instead of the JavaFX Packager tool.

2.5 User Experience

Users are easily annoyed if they are unable to start an application, do not understand what are the next steps, or perceive the application as slow or hung and for many other reasons.

Default JavaFX packaging takes care of many problem areas including:

  • Ensuring the user has the required JRE and JavaFX installed

  • Auto installing missing dependencies or offering to install them as needed

  • Providing visual feedback to the user while the application is being loaded

  • Showing descriptive error messages

For example, when users do not have JavaFX installed and double-click the JAR file for your application, they see a dialog box explaining that they need to download and install the JavaFX Runtime.

Moreover, developers have a wide range of options on how to tune the experience for their users, such as:

  • Customize the messaging (for example explain to users why they need to install JavaFX Runtime in a language other than English)

  • Show your own splash screen and use a custom loading progress indicator

  • Switch to alternative content if the user's system is not capable of running JavaFX applications

For example, you could pass the following string as a value of the javafx.default.preloader.stylesheet parameter to add a company logo to the default preloader:

".default-preloader { -fx-preloader-graphic:url
(''); }"

In Example 2-3, the text in bold shows what must be changed in the Ant code used to deploy the ColorfulCircles example.

Example 2-3 Ant Task to Add a Company Logo to the Default Preloader

<fx:deploy width="800" height="600"
        outdir="dist-web" outfile="ColorfulCircles">
    <fx:info title="Colorful Circles"/>
    <fx:application name="Colorful Circles example"
        <fx:param  name="javafx.default.preloader.stylesheet"
                { -fx-preloader-graphic: url(''); }" />
        <fx:fileset dir="dist-web" includes="ColorfulCircles.jar"/>

See the following chapters for more information and examples:

2.6 Getting the Most Out of the Execution Environment

Different execution environments have different specifics, and taking these specifics into account can help to make an application more natural and powerful when run in this execution environment.

One specific could be a unique feature that is not applicable to other environments, for example that applications embedded in a web page can use JavaScript to communicate to the host web page. Another specific could be an important peculiarity such as a presized stage that is provided to a JavaFX application embedded into a web page.

Example 2-4 shows an example of using JavaScript to go to a new page:

Example 2-4 Using JavaScript to Go to a New Page

final HostServices services = getHostServices();
JSObject js = services.getWebContext();

See the following pages for more information and examples:

2.7 Deploying Swing and SWT Applications with Embedded JavaFX Content

If you are developing Swing applications with embedded JavaFX content, then you must follow deployment scenarios for Swing applications and applets (see the Swing tutorial for tips on coding).

While most of the techniques discussed in this guide are not directly applicable to Swing application with JavaFX content some of them are:

  • You can use the same packaging tools to package your Swing applications.

  • You can use the Deployment Toolkit to embed your Swing applet into a web page or launch it from a web page.

  • Your application can be bundled and packaged as an installable package, using the same technique as for self-contained JavaFX applications.

For more information, see Chapter 10, "JavaFX in Swing Applications".

SWT applications with embedded JavaFX content are deployed in the same manner as Swing applications, but the SWT library must be included as a resource. For an example of deploying an SWT-JavaFX application, see JavaFX Interoperability with SWT.