How does CheerpJ work?

CheerpJ is a WebAssembly-based Java Virtual Machine for the browser. This means Java applications can be executed from the browser with no Java installations. Amazing, right? but… How does it work?


CheerpJ runs in any modern browser using standard Web technologies, particularly WebAssembly, JavaScript, and HTML5. It can be integrated into a web page like any JavaScript library, by simply adding a <script> tag. It requires no custom executable component, plugin, or server-side backend.

CheerpJ is very simple to use as it exposes an API for executing standalone Java applications, applets, Java Web Starts, and Java libraries - entirely in the browser. One of the strengths of CheerpJ is that it works directly with Java byte code/JARs, meaning no need to modify or have access to the application’s source code.

CheerpJ assets are static, which makes it easily self-hostable, and we provide a cloud version under the CheerpJ Community Licence (free to use for personal projects and technical evaluations).

CheerpJ components

CheerpJ is made of the following building blocks:

  • A full Java runtime environment with its implementation of the JVM and a Java-to-JavaScript JIT compiler.
  • A virtualized window manager
  • A virtualized file system
  • A module for networking support

CheerpJ 3.0 architecture diagram

The CheerpJ Java Runtime Environment

The magic behind CheerpJ is Cheerp, which was used for compiling a full Java SE 8 runtime based on OpenJDK. This runtime was originally written in C++ and compiled to WebAssembly and JavaScript, making it 100% browser compatible. The architecture is designed to support multiple versions of Java, as well as custom runtimes. Future versions of CheerpJ will support Java 11, and newer LTS Java versions.

The most important component of the CheerpJ Java runtime environment is its JVM implementation. CheerpJ’s implementation of the JVM is made of an interpreter and a Just In Time compiler (JIT) that work in conjunction in a 2-tier manner:

  1. The Java byte code runs within an interpreter.
  2. Then this byte code is Just-In-Time compiled to optimized JavaScript.

The interpreter does not only deal with initialization and rarely-used code, but also gathers necessary information for JIT-ting. The generated code is very efficient, and the internal optimizer can, among other things, inline and devirtualize calls, which is extremely important for a language such as Java.

CheerpJ 3.0 JRE diagram

Alongside being able to run Java applications in the browser, CheerpJ runtime also provides advanced, bidirectional Java-JavaScript interoperability. Meaning you can access DOM from Java by implementing native methods directly in JavaScript. You can also interact with Java methods, objects and arrays directly from JavaScript by using the new cheerpjRunLibrary API.

The virtualized window manager

What would be of an application without its graphical UI? CheerpJ’s window manager supports Java AWT/Swing by converting windows to a hierarchy of HTML elements and HTML5 canvases.

Swing applications, will render exactly as they do in native. Swing Look&Feel is also supported, including 3rd party ones. Multi-window applications are supported, with keyboard focus being managed as expected. Integration with the system clipboard can be enabled via an initialization option.

The virtualized file system

CheepJ provides multiple filesystem backends to accommodate different application needs, including access to server-hosted files and persistent local storage.

File System guide

Networking support

For same-origin HTTP/HTTPS requests, CheerpJ will be able to transparently use fetch. More generalized networking is supported via Tailscale, a VPN technology using WebSockets as a transport layer. It can support many different networking scenarios, including access to private network services, peer-to-peer connections between users and access to the wider internet via a user/application provided exit node. CheerpJ 3.0 general networking

Networking guide
Was this page helpful?
Suggest changes