Run a Java App in the Browser (SwingSet3)

Porting a Swing application to the web

This tutorial runs SwingSet3, the Swing demo application, in the browser with CheerpJ.

Prerequisites

Node.js (>= 18)
A copy of the tutorial repository

  git clone https://github.com/leaningtech/cheerpj-meta.git

Go to the projectTemplate directory of the SwingSet3 example:

  cd examples/SwingSet3/projectTemplate

The starting point is an HTML page, the SwingSet3 JAR and its dependencies:

projectTemplate/
├── index.html
├── SwingSet3.jar
└── lib
    ├── AnimatedTransitions.jar
    ├── AppFramework.jar
    ├── javaws.jar
    ├── swing-worker.jar
    ├── swingx.jar
    └── TimingFramework.jar

1. Run a web server

CheerpJ loads the application from a web server, so the files must be served over HTTP. Vite works well during development because it reloads the page when the files change.

npx vite

Open the URL shown in the terminal. The page is blank. Leave Vite running for the rest of this tutorial.

Alternatively, use the http-server utility:

npx http-server -p 8080

Then open http://127.0.0.1:8080/ in the browser.

Note

The server must support HTTP Range requests, and the page cannot be opened from file://. Python’s http.server does not support Range requests. See basic server setup.

2. Open `index.html` and add CheerpJ to the document

The template is a minimal HTML page. Add the CheerpJ loader to the <head>:

<script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script>

3. Initialise CheerpJ and run the JAR

Add the following script tag to the <body>:

<script type="module">
  await cheerpjInit();
  cheerpjCreateDisplay(800, 600);
  await cheerpjRunJar("/app/SwingSet3.jar");
</script>

This initialises CheerpJ, creates an 800x600 display and runs the SwingSet3 JAR. The script uses type="module" so that it can use top-level await. See cheerpjInit, cheerpjCreateDisplay and cheerpjRunJar for the options each function takes.

What is /app/SwingSet3.jar?

/app/ is a mount point of the CheerpJ virtual file system. It maps to the root of the web server, so /app/SwingSet3.jar is the file served at /SwingSet3.jar. The JARs in lib/ are found through the Class-Path entry in the manifest of SwingSet3.jar.

Save the file. SwingSet3 loads and runs in the browser.

4. Make the application take up the whole page

The application takes up a small part of the page. To make it fill the page, add a container element to the <body>:

<div id="container"></div>

Note

Make sure you add the container element before the script which calls cheerpjCreateDisplay.

Then add some CSS to the <head>:

<style>
  html,
  body {
    margin: 0;
  }

  #container {
    width: 100vw;
    height: 100svh;
  }
</style>

Finally, update the script to use the container element:

<script type="module">
  await cheerpjInit();
  cheerpjCreateDisplay(-1, -1, document.getElementById("container"));
  await cheerpjRunJar("/app/SwingSet3.jar");
</script>

Passing -1 as the width and height makes the display match the size of the container element and follow it when it is resized.

Reload the page. The application fills the window, and resizing the window resizes the application.

The result

Source code

View full source code on GitHub