Embed CheerpJ in your application

Software vendors with a Java desktop client can ship CheerpJ inside their product, so their customers run the same client in the browser. The web edition comes from the same codebase as the desktop edition, and the Java code runs on the user’s own device.

Playground Documentation

CheerpJ is a Java runtime for the browser, built from OpenJDK and compiled to WebAssembly. It loads with a single script tag and draws your client’s window inside an element of your own page.

index.html

<script src="https://cjrtnc.leaningtech.com/4.3/loader.js"></script>
<div id="client"></div>
<script type="module">
  await cheerpjInit({ version: 17 });
  cheerpjCreateDisplay(-1, -1, document.getElementById("client"));
  await cheerpjRunJar("/app/your-client.jar");
</script>

Embed your client in four steps

CheerpJ runs your client’s compiled JAR files, so the web edition uses the same build as the desktop edition.

To get started, you need:

Your client’s JAR files
A page in your web application to host it
A web server that supports HTTP range requests

Add CheerpJ to the page

Add CheerpJ’s loader script, then call cheerpjInit to start the runtime. The version option sets the Java version your client runs on.
index.html
```
<script src="https://cjrtnc.leaningtech.com/4.3/loader.js"></script>
<script type="module">
  await cheerpjInit({ version: 17 });
</script>
```

Place the client’s window in your page

cheerpjCreateDisplay draws the client inside an element of your page. Pass a width and height, or -1 for both to fill the element.

index.html

<div id="client"></div>
<script type="module">
  await cheerpjInit({ version: 17 });
  const el = document.getElementById("client");
  cheerpjCreateDisplay(-1, -1, el);
</script>

Start the client

Call cheerpjRunJar with the path to your JAR, or cheerpjRunMain with the main class and class path if the client starts another way. /app/ is the root of your web server.
JavaScript
```
await cheerpjRunJar("/app/your-client.jar");

// Or start by main class
await cheerpjRunMain(
"com.example.Main",
"/app/client.jar:/app/lib.jar"
);
```
Host the files

Serve CheerpJ and your client as static files from your own web servers or a CDN. For production, you can record the runtime components your client uses and preload them, which shortens the first start.

The result

Open the page and your client starts inside it. CheerpJ downloads the runtime components the client needs, typically 10 to 20 MB for many applications, and the browser caches them for later visits.

Key features

A full Java runtime

CheerpJ is built from OpenJDK and runs your client on Java 8, 11, 17 and 21, with Java 25 in preview.

Your compiled code as it is

CheerpJ runs your bytecode, including obfuscated code, custom class loaders and third-party libraries.

Swing and AWT in your page

A virtual window manager draws Swing and AWT interfaces with HTML elements and canvases, inside the element you choose.

Java and JavaScript together

Library mode lets your web interface create Java objects and call their methods, and Java native methods can be written in JavaScript to reach browser features.

Files

A virtual filesystem serves files from your web server and keeps data in the browser between sessions. Users upload files to the client and save files to their computer.

Networking

HTTP requests go through the browser. TCP and UDP connections go through Tailscale, with a control server you can host on your customers’ networks.

Start-up

CheerpJ downloads runtime components as the client needs them, and you can preload the ones it uses to shorten the first start.

Static hosting

CheerpJ and your client are static files, served from any web server or CDN, in hosted and on-premises deployments, including air-gapped networks.

Central updates

Customers run the new version of your client the next time they open the page, including on Chromebooks and locked-down PCs.

Frequently asked questions

More FAQs

What do customers need to run the client?

A browser. Customers open your client in Chrome, Edge, Firefox or Safari, including on Chromebooks and computers where they can’t install software.

Can the client sit inside our existing web interface?

Yes. cheerpjCreateDisplay places the client’s window inside an element of your page, at a fixed size or filling the element, and CheerpJ works with frameworks such as React. The reference covers the options.

Can our web interface call the client’s Java code?

Yes. In library mode, JavaScript creates Java objects and calls their methods with async and await, as the library mode guide shows. In the other direction, Java native methods can be implemented in JavaScript, as the native methods guide explains.

Which Java versions does CheerpJ support?

Java 8, 11, 17 and 21, with Java 25 in preview.

How is CheerpJ licensed in a product we sell?

Redistribution and OEM use are covered by the CheerpJ Commercial License, and products are licensed per application. Resellers and system integrators have a separate agreement. The licensing page sets out the terms.

Learn more about CheerpJ

Case Studies · 11 October 2022

Embed CheerpJ in your application

Embed your client in four steps

Add CheerpJ to the page