cheerpjInit

Set up and initialize the CheerpJ runtime environment

cheerpjInit must be called once in the page to setup and initialise the CheerpJ runtime environment.

async function cheerpjInit(options?: {
  version?: number;
  status?: "splash" | "none" | "default";
  logCanvasUpdates?: boolean;
  preloadResources?: { [key: string]: number[] };
  preloadProgress?: (preloadDone: number, preloadTotal: number) => void;
  clipboardMode?: "permission" | "system" | "java";
  beepCallback?: () => void;
  enableInputMethods?: boolean;
  overrideShortcuts?: (evt: KeyboardEvent) => boolean;
  appletParamFilter?: (originalName: string, paramValue: string) => string;
  natives?: { [method: string]: Function };
  overrideDocumentBase?: string;
  javaProperties?: string[];
  tailscaleControlUrl?: string;
  tailscaleDnsIp?: string;
  tailscaleAuthKey?: string;
  tailscaleLoginUrlCb?: (url: string) => void;
  tailscaleIpCb?: (ip: string) => void;
  licenseKey?: string;
  execCallback?: (cmdPath: string, argsArray: string[]) => void;
  enableDebug?: boolean;
  hostName?: string;
  disableScaling?: boolean;
  env?: string[];
  wasmGC?: boolean;
}): Promise<void>;

Parameters

options (object, optional) - Used to configure different settings of the CheerpJ runtime environment in the form { option: "value" }.

Returns

cheerpjInit returns a Promise which is resolved when the CheerpJ runtime environment is ready to be used.

Options

A description of each cheerpjInit() option with brief examples are given below.

`version`

version?: number;

The Java runtime version to use. Java 8, 11, 17, 21 and 25 are currently supported. Default version is Java 8 if not specified.

Java 21 and 25 require CheerpJ 5.0

Java 21 and 25 are only available from CheerpJ version 5.0. Earlier versions support Java 8, 11 and 17.

Java Applets and Java 8

Please notice that Applets are supported on Java 8 only.

`status`

status?: "splash" | "none" | "default";

This option determines the level of verbosity of CheerpJ in reporting status updates.

"default": Enables status reporting during initialization and short-lived “Loading…” messages every time new runtime code is being downloaded.
"splash": Enabled status reporting only during initialization. There will be no feedback after the first window is shown on screen.
"none": Disable all status reporting.

Example:

cheerpjInit({ status: "splash" });

`logCanvasUpdates`

logCanvasUpdates?: boolean;

When set to true, it enables logs on the console about the display areas which are being updated. Useful to debug overdrawing.

Example:

cheerpjInit({ logCanvasUpdates: true });

`preloadResources`

preloadResources?: { [key: string]: number[] };

By using preloadResources, you can provide CheerpJ with a list of runtime files which you know in advance will be required for the specific application. The list is an object that maps each runtime file to the byte ranges of it to load. Generate it with cjGetRuntimeResources rather than writing it by hand.

Example:

cheerpjInit({ preloadResources: {"/lts/file1.jar":[int, int, ...], "/lts/file2.jar":[int,int, ...]} });

`preloadProgress`

preloadProgress?: (preloadDone: number, preloadTotal: number) => void;

This callback may be used in combination with preloadResources to monitor the loading of an application. The information provided is useful, for example, to display a loading/progress bar.

Example:

function showPreloadProgress(preloadDone, preloadTotal) {
  console.log("Percentage loaded " + (preloadDone * 100) / preloadTotal);
}

await cheerpjInit({ preloadProgress: showPreloadProgress });

`clipboardMode`

clipboardMode?: "permission" | "system" | "java";

This option allows you to configure how the clipboard will behave. Supported clipboard modes are java, system and permission.

Example:

cheerpjInit({ clipboardMode: "system" });

`java` mode

This is the default setting. CheerpJ supports an internal clipboard which is local to the Java application and is not integrated with the system clipboard.

`system` mode

In system mode CheerpJ will share the clipboard with the system. Browsers enforce serious limitations on how the system clipboard can be accessed. In practice it is generally accessible when the Ctrl+C and Ctrl+V shortcuts are used (Cmd+C and Cmd+V on MacOSX). Due to these limitations the UX when using clipboardMode:"system" is:

Ctrl+C/Cmd+C: the user has to press the shortcut twice to give CheerpJ access to the system clipboard. CheerpJ will block the execution while waiting for the second Ctrl+C.
Ctrl+V/Cmd+V: this shortcut behaves normally, there is no difference with native execution.
Menu based Copy/Paste: Ctrl+C/Ctrl+V are needed to access the clipboard. CheerpJ will block the execution while waiting the appropriate shortcut.

`permission` mode

With permission mode enabled, CheerpJ offers a more seamless integration than system mode. This includes support for images and HTML on top of plain text. Another important feature is that pressing extra Ctrl+C/Ctrl+V to perform copying and pasting operations is not required.

The first time an operation is requested, the user will be asked for permission to use the clipboard. If this permission is refused, a message will be prompted explaining this permission is necessary to continue.

HTTP limitations in permission mode

The internal browser clipboard API to access any clipboard data is only available over a secure context (HTTPS). When the application is accessed over HTTP, browsers enforce serious limitations on how the system clipboard can be accessed. Users can only copy and paste text to the page itself and will have to double press Ctrl+C and Ctrl+V (Cmd+C and Cmd+V on macOS).

To resolve this issue:

Using an HTTPS proxy.

Enable the page as a secure context using browser settings.

This mode is experimental and might show a few inconsistencies in some browsers. See more.

`beepCallback`

beepCallback?: () => void;

This callback runs when java.awt.Toolkit.getDefaultToolkit().beep() is called in Java. It corresponds to the system’s beep sound.

Example of usage:

cheerpjInit({
  beepCallback: function () {
    alert("Beep!");
  },
});

`enableInputMethods`

enableInputMethods?: boolean;

When this option is set to true CheerpJ will be able to receive text input from the input method framework of the platform. This is useful to support text input for languages such as Chinese, Japanese and Korean.

cheerpjInit({ enableInputMethods: true });

Important

This option is enabled by default in CheerpJ 4.0 and newer, to disable it set it to false.

`overrideShortcuts`

overrideShortcuts?: (evt: KeyboardEvent) => boolean;

Some applications needs to internally handle keyboard shortcuts which are also used by the browser, for example Ctrl+F. Most users expect the standard browser behavior for these shortcuts and CheerpJ does not, by default, override them in any way.

A CheerpJ-compiled application can take control of additional shortcuts by providing a callback function as the overrideShortcuts options of cheerpjInit. This callback receives the KeyboardEvent coming from the browser and should return true if the default browser behaviour should be prevented.

Whenever possible we recommend not to use browser reserved shortcuts, to maintain a consistent user experience. In any case, the following limitations apply:

Some shortcuts (Ctrl+T, Ctrl+N, Ctrl+W) are reserved by the browser and never received by the page itself. These cannot be overridden
Overriding (Ctrl+C/Ctrl+V) will prevent clipboardMode:"system" from working correctly.

Example:

cheerpjInit({
  overrideShortcuts: function (e) {
    // Let Java handle Ctrl+F
    if (e.ctrlKey && e.keyCode == 70) return true;
    return false;
  },
});

`appletParamFilter`

appletParamFilter?: (originalName: string, paramValue: string) => string;

Some applications may need to have some parameter modified before getting those inside the applet.

Example:

cheerpjInit({
  appletParamFilter: function (name, value) {
    if (name === "httpServer") return value.replace("http", "https");
    return value;
  },
});

`natives`

natives?: { [method: string]: Function };

This option is used to implement native methods from an AOT-compiled language in JavaScript.

Example usage:

cheerpjInit({
  natives: {
    async Java_MyClass_myMethod(lib, str) {
      window.alert(str);
    },
  },
});

Read more about implementing native methods here.

`overrideDocumentBase`

overrideDocumentBase?: string;

Replaces the current <base> URL of the document with the URL passed as a string.

Example usage:

cheerpjInit({ overrideDocumentBase: "YourNewURLHere" });

`javaProperties`

javaProperties?: string[];

An array of Java properties in the form "key=value". They will be defined on the System object (System properties). This option should be used if command line arguments in the form -Dkey=value are required when using native Java.

Example usage:

cheerpjInit({ javaProperties: ["prop1=value1", "prop2=value2"] });

`tailscaleControlUrl`

tailscaleControlUrl?: string;

This option expects a string URL of the Tailscale control plane. The control plane verifies the user’s identity and validates various keys among the connected peers in the network. Only pass this option if you are self-hosting Tailscale, if omitted, it will point to the Tailscale control plane.

Example usage:

cheerpjInit({ tailscaleControlUrl: "https://my.url.com/" });

`tailscaleDnsIp`

 tailscaleDnsIp?: string;

Expects a string with the IPv4 or IPv6 address to use for DNS queries. If omitted, the default IP address is “8.8.8.8”.

Example usage:

cheerpjInit({ tailscaleDnsIp: "1.1.1.1" });

`tailscaleAuthKey`

tailscaleAuthKey?: string;

This option expects a string that contains a Tailscale auth key. Using auth keys allows one to register new users/devices that are pre-authenticated. You can create an auth key here. This option is mutually exclusive with tailscaleLoginUrlCb

Info

A combination of a user and a device connected to a Tailscale network is called a “node” in Tailscale terminology.

For more information about auth keys visit the Tailscale auth keys documentation.

Example of usage:

cheerpjInit({ tailscaleAuthKey: "AuthKeyStringGoesHere" });

`tailscaleLoginUrlCb`

tailscaleLoginUrlCb?: (url: string) => void;

This option is used to login into a Tailscale network and it is mutually exclusive with tailscaleAuthKey. It is a callback that CheerpJ calls with a login URL when it is time to prompt the user to log in to Tailscale. Show the URL to the user, for example as a link or in a new window, to continue and finish the login process.

For more information visit the Tailscale documentation.

cheerpjInit({
  tailscaleLoginUrlCb(url) {
    // your function code here to continue with login
  },
});

`tailscaleIpCb`

tailscaleIpCb?: (ip: string) => void;

This callback is used to retrieve the IP address of the client once the connection with the Tailscale network is established.

Example of usage:

cheerpjInit({
  tailscaleIpCb: function (ip) {
    console.log("IP address " + ip);
  },
});

`licenseKey`

licenseKey?: string;

This option expects a license key. The non-commercial license message will be removed from the CheerpJ display if a valid license key is used. Please visit our licensing guide for more information.

Example of usage:

cheerpjInit({ licenseKey: "YourLicenseKey" });

`execCallback`

Supported since CheerpJ version 3.1

execCallback?: (cmdPath: string, argsArray: string [])  => void;

This option allows you to intercept and handle external system commands or program executions that initiated from a Java application. Such commands are typically executed using methods like Runtime.getRuntime().exec(command) or new ProcessBuilder(command) in Java.

The callback function accepts two parameters:

cmdPath: The command that would have been executed in Java.
argsArray: An array of additional arguments passed to that command.

Example of usage:

cheerpjInit({
  execCallback: function (cmdPath, argsArray) {
    debugger;
  },
});

Learn more about the execCallback option in our intercept external commands guide.

`enableDebug`

Supported since CheerpJ version 3.1

enableDebug?: boolean;

This option enables advanced debug logging, which is helpful for troubleshooting issues with CheerpJ. Be aware it can significantly affect performance. Disable it when not needed.

Example of usage:

cheerpjInit({ enableDebug: true });

Learn more about how to debug CheerpJ in our Debugging CheerpJ guide.

`hostName`

Supported since CheerpJ version 4.3

hostName?: string;

This option will set the hostname of the JVM to the string passed as an argument. This is the value returned when calling the standard Java functions getHostName() or getHostAddress() from the java.net.InetAddress package. These functions are used, for instance, by Oracle’s WebUtil component.

If this option is not provided, CheerpJ defaults to the arbitrary IP address 192.168.1.1.

Example of usage:

cheerpjInit({ hostName: "10.10.90.200" });

`disableScaling`

Supported since CheerpJ version 4.3

disableScaling?: boolean;

This option turns off CheerpJ display scaling on high-DPI screens. This often resolves text rendering issues where text appears truncated.

Example of usage:

cheerpjInit({ disableScaling: true });

`env`

Supported since CheerpJ version 5.0

env?: string[];

Sets environment variables for the Java runtime. Use this option when your application or a library depends on environment values via System.getenv().

The option takes an array of strings in the form "key=value". Variables are set once at initialization and cannot be changed afterward.

Example usage:

cheerpjInit({ env: ["env1=value1", "env2=value2"] });

To pass JVM system properties instead, see javaProperties.

`wasmGC`

Supported since CheerpJ version 5.0

wasmGC?: boolean;

This option enables the experimental WasmGC engine in the CheerpJ Java runtime.

Important

The wasmGC option requires a current browser: Chrome and Edge 137 or later, Firefox 153 or later, and Safari 27 or later (iOS and iPadOS 27 on mobile).

Example of usage:

cheerpjInit({ wasmGC: true });

cheerpjInit

Parameters

Returns

Options

version

status

logCanvasUpdates

preloadResources

preloadProgress

clipboardMode

java mode

system mode

permission mode

beepCallback

enableInputMethods

overrideShortcuts

appletParamFilter

natives

overrideDocumentBase

javaProperties

tailscaleControlUrl

tailscaleDnsIp

tailscaleAuthKey

tailscaleLoginUrlCb

tailscaleIpCb

licenseKey

execCallback

enableDebug

hostName

disableScaling

env

wasmGC

Build with Java for the browser.

`version`

`status`

`logCanvasUpdates`

`preloadResources`

`preloadProgress`

`clipboardMode`

`java` mode

`system` mode

`permission` mode

`beepCallback`

`enableInputMethods`

`overrideShortcuts`

`appletParamFilter`

`natives`

`overrideDocumentBase`

`javaProperties`

`tailscaleControlUrl`

`tailscaleDnsIp`

`tailscaleAuthKey`

`tailscaleLoginUrlCb`

`tailscaleIpCb`

`licenseKey`

`execCallback`

`enableDebug`

`hostName`

`disableScaling`

`env`

`wasmGC`