Skip to content

Getting Started

Alessandro Pignotti edited this page Feb 16, 2020 · 23 revisions

This page will help you getting started with CheerpJ and converting your first Java application to JavaScript in no time.

To start, make sure to download the latest available version of CheerpJ here. Decompress the Cheerpj 2.0 archive anywhere, for example in ~/cheerpj_2.0.

Important: Converting an applet is documented at the bottom of this page.

Converting a single JAR to a JAR.JS file is an helper script that automatically takes care of unpacking, compiling and optimising a whole JAR archive. Using is the recommended way of compiling applications and libraries using CheerpJ.

The basic usage is very simple:

~/cheerpj_2.0/ my_application_archive.jar

This command will generate a file called my_application_archive.jar.js, which needs to be deployed in the same folder of the original .JAR archive, and hosted on a web server. Instructions on how to serve the converted JavaScript on a web page are provided below.

Important: The files must be accessed through a Web server. Trying to open the HTML page directly from the disk is not supported. The URL must look like, if it looks like file://c/users/Test/cheerpj_test.html CheerpJ won't be able to start.

Note to Windows users: You will need to have python3 installed on the system. Python provides a launcher called py that will automatically detect and use the right version of python for a given script. To use on Windows you need to prefix all the commands with py, for example:

py c:\cheerpj_2.0\ application.jar

Converting multiple JARs to JAR.JS's files

If your JAR has any dependencies in the form of further JAR archives, the command line must be modified as follows:

~/cheerpj_2.0/ --deps my_dependency_archive.jar my_application_archive.jar

This command will generate my_application_archive.jar.js but not my_dependency_archive.jar.js. Each archive should be compiled separately by invoking ~/cheerpj_2.0/ my_dependency_archive.jar.

It is in general safe to put the target JAR in the --deps list, although it is not required. If you have an application composed of many JARs you can do something like this:

for f in one.jar two.jar three.jar
    ~/cheerpj_2.0/ --deps one.jar:two.jar:three.jar $f

Basic HTML page for testing

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8">
    <title>CheerpJ test</title>
    <script src=""></script>
      cheerpjRunMain("AppClass", "/app/my_application_archive.jar:/app/my_dependency_archive.jar"); 

This page will initialize the CheerpJ system, create a graphical environment to contain all Java windows and then execute the main method of AppClass. The second parameter of cheerpjRunMain is a : separated list of JARs where application classes can be found (the classpath). The /app/ is a virtual file system mount point that reference the root of the web server this page is loaded from.

You can now serve this web page on a simple http server, such as the http-server utility.

http-server ~/cheerpj_2.0/

Converting an applet

Applets can be run by Chrome users using the CheerpJ Applet Runner Chrome extension. You can also compile the applet ahead of time using the method described above.

To support all browsers, you can add the following tags to your page:

<script src=""></script>

This should be sufficient to get the applet to run on any browser, with the pre-compiled JAR.JS's files deployed in the same directory of the the original JAR files. The cheerpjInit(); call can be done during page initialization, to avoid potential conflicts with native java we recommend replacing the original HTML tag with cheerpj- prefixed version. You should use <cheerpj-applet>, <cheerpj-object> or <cheerpj-embed> depending on the original tag.

You can’t perform that action at this time.