Run a Java application

Convert a desktop app to a webapp

CheerpJ can run a Java application in the browser with little to no modifications. This page will help you getting started with CheerpJ and running your first Java application in the browser.

Java source code is not needed to use CheerpJ. If you are building your own application you should already have its .jar file(s).

To get started you will need:

  • Your Java application file(s). You can also use this TextDemo.jar sample.
  • An HTML file where your Java app will be wrapped
  • A simple HTTP server to test your webpage locally

1. Create a project directory

Let’s start by creating a project folder where all your files will be. Please copy your java and future HTML files here.

Terminal window
mkdir directory_name

2. Create a basic HTML file

Let’s create a basic HTML file like the following example. Please notice the CheerpJ runtime environment has been integrated and initialized. In this example we are assuming your HTML file and your .jar files are under the project directory you just created.

<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<title>CheerpJ test</title>
<script src=""></script>
(async function () {
await cheerpjInit();
cheerpjCreateDisplay(800, 600);
await cheerpjRunJar("/app/my_application_archive.jar");

Alternatively, if your application is not designed to be executed with the command java -jar you can replace cheerpjRunJar() for cheerpjRunMain() and pass your qualified class name as an argument. For example:


3. Host your page

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

Terminal window
npx http-server -p 8080
Opening the page directly from the disk (for example, by double-clicking on it) is not supported.

What’s going on?

  • The <head> script loads CheerpJ.
  • cheerpjInit initialises the CheerpJ runtime environment.
  • cheerpjCreateDisplay creates a graphical environment to contain all Java windows.
  • cheerpjRunJar executes your application!
  • /app/ is a virtual filesystem mount point that references the root of the web server this page is loaded from.

The result

You will see the CheerpJ display on your browser with some loading messages before showing your application running. Depending on your application and the optimizations applied, this could take just a few seconds.

Further reading

Was this page helpful?
Suggest changes