---
title: "Run a JNLP"
source: "https://cheerpj.com/docs/getting-started/JNLP"
---

# Run a JNLP

Run a JWS/JNLP application in the browser

This page takes you step by step from a Java Web Start (JNLP) application to the same application running in the browser with CheerpJ. You read the JAR files and the main class from the `.jnlp` file, then start the application from your own HTML page.

Not a developer?

The JNLP Runner browser extension opens Java Web Start applications from the pages users already launch them from, with no changes to the page.

[Run Java Web Start apps in your browser.](https://cheerpj.com/extensions/)

[JNLP Runner](https://cheerpj.com/extensions/)

**To get started you will need:**

- The application’s `.jnlp` file.
- An HTML page to run the application from.
- An HTTP server that supports Range requests, to test the page locally.

## 1. The `.jnlp` file

The `.jnlp` file describes how to launch a Java Web Start application. Normally a website serves this file, the user’s local Java Web Start client downloads the JAR files it lists, and the application runs on the Java installation on the user’s computer. **With CheerpJ the application runs in the browser sandbox instead, with no Java installation.**

Your `.jnlp` file might look like the example below. Find these elements in it:

1. The JAR files under `<resources>`, listed in `<jar>` tags.
2. The application type: an `<application-desc>` or an `<applet-desc>` tag.
3. The `codebase` URL in the `<jnlp>` tag, if the JAR URLs are relative.

`example.jnlp`

```xml
<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP Example -->
<jnlp
  spec="1.0+"
  codebase="code-base-url"
  href="example.jnlp">
  <information>
    <title>Your application name</title>
    <vendor>Vendor name</vendor>
    <homepage href="home-page-url"/>
    <description>Description of your Java application</description>
    <description kind="short">Another description of your Java application</description>
    <icon href="image-url"/>
    <icon kind="icon-name" href="image-url"/>
    <offline-allowed/>
  </information>
  <security>
      <all-permissions/>
  </security>
  <resources>
    <j2se version="1.4+" initial-heap-size="64m" max-heap-size="640m"/>
    <jar href="my_application_archive.jar"/>
    <jar href="lib/my_dependency.jar"/>
    <property name="key" value="overwritten"/>
  </resources>
  <application-desc main-class="com.application.MyClassName"/>
</jnlp>
```

The other elements need no action, with two exceptions:

- `<property>` elements set Java system properties. Pass them to [`cheerpjInit()`](https://cheerpj.com/docs/reference/cheerpjInit.md) with the [`javaProperties`](https://cheerpj.com/docs/reference/cheerpjInit.md#javaproperties) option, for example `cheerpjInit({ javaProperties: ["key=overwritten"] })`.
- `<nativelib>` elements list JARs of pre-built native libraries (`.dll`, `.so` or `.dylib` files), which cannot run in the browser. If the application needs them, implement its native methods [in JavaScript](https://cheerpj.com/docs/guides/implementing-native-methods.md) or compile them to WebAssembly instead.

CheerpJ ignores the `<j2se>` element: the application runs on the Java version [`cheerpjInit()`](https://cheerpj.com/docs/reference/cheerpjInit.md) chooses, Java 8 by default. JNLP applets run on Java 8 only; a standalone JNLP application can use another version with the [`version`](https://cheerpj.com/docs/reference/cheerpjInit.md#version) option.

## 2. Create a project directory

Download each JAR listed in a `<jar>` tag by opening its URL in the browser. If the URLs are relative, build the full URL by joining the `codebase` URL and the `href` of the `<jar>` tag.

For example:

```plaintext
code-base-url/my_application_archive.jar
code-base-url/lib/my_dependency.jar
```

Create a directory for the project and place the downloaded JARs inside it, keeping the directory structure of the `href` paths in the `.jnlp` file.

For example:

```shell
mkdir -p my-project/lib
```

With the JARs in place, the directory looks like this:

```plaintext
└── my-project
    ├── my_application_archive.jar
    └── lib
        └── my_dependency.jar
```

## 3. Create a basic HTML file

### 3.1 Identify your application type

A JNLP app is either a **standalone application** or an **applet**. The `.jnlp` file shows which: it has an **`<application-desc>`** tag for an application and an **`<applet-desc>`** tag for an applet.

Create an `index.html` file in the root of the project directory. The HTML is different for each type, as the next sections show.

### 3.2 If your application is a standalone app

Look at the `<application-desc>` tag and note:

- **The application class name:** the `main-class` attribute. If it is missing, the main class is named in the manifest of the main JAR.
- **The application arguments:** any `<argument>` elements inside the tag, in order.

If the `.jnlp` file gives a `main-class`, start the application with [`cheerpjRunMain()`](https://cheerpj.com/docs/reference/cheerpjRunMain.md), passing the class name and all the JARs separated by `:`:

`index.html`

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>CheerpJ test</title>
    <script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script>
  </head>
  <body>
    <script type="module">
      await cheerpjInit();
      cheerpjCreateDisplay(800, 600);
      await cheerpjRunMain(
        "com.application.MyClassName",
        "/app/my_application_archive.jar:/app/lib/my_dependency.jar"
      );
    </script>
  </body>
</html>
```

If there is no `main-class` attribute, use [`cheerpjRunJar()`](https://cheerpj.com/docs/reference/cheerpjRunJar.md) with the main JAR instead. This finds the main class in the JAR’s manifest, as `java -jar` does, and the dependencies through the manifest’s `Class-Path`:

```js
await cheerpjRunJar("/app/my_application_archive.jar");
```

Pass the application arguments to [`cheerpjRunMain()`](https://cheerpj.com/docs/reference/cheerpjRunMain.md) or [`cheerpjRunJar()`](https://cheerpj.com/docs/reference/cheerpjRunJar.md) after the class path or JAR name, one string per `<argument>`.

The `/app/` prefix is a [virtual filesystem](https://cheerpj.com/docs/guides/filesystem.md) mount point for the root of the web server the page is loaded from, so `/app/lib/my_dependency.jar` is the file `lib/my_dependency.jar` in the project directory.

### 3.3 If your application is an applet

Look at the `<applet-desc>` tag in the `.jnlp` file and note:

- **The applet class name:** the `main-class` attribute.
- **The applet size:** the `width` and `height` attributes.
- **The applet parameters:** any `<param>` elements inside `<applet-desc>`.
- **The `documentBase` attribute**, if present: the URL of an HTML page that embeds the applet. You can start from that page, adding the CheerpJ scripts to it, or write your own HTML like the example below.

Put these into an `<applet>` tag. List all the JARs in the `archive` attribute, separated by commas, with paths relative to the page:

`index.html`

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>CheerpJ applet test</title>
    <script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script>
  </head>
  <body>
    <applet
      archive="my_application_archive.jar,lib/my_dependency.jar"
      code="com.applet.MyClassName"
      height="900"
      width="900"
    ></applet>
    <script>
      cheerpjInit();
    </script>
  </body>
</html>
```

Pass any applet parameters as `<param>` elements inside the `<applet>` tag, as usual:

```html
<applet
  archive="my_application_archive.jar,lib/my_dependency.jar"
  code="com.applet.MyClassName"
  height="900"
  width="900"
>
  <param name="paramName" value="paramValue" />
</applet>
```

If some of your users still have the native Java plug-in installed, rename the tag with a `cheerpj-` prefix so that only CheerpJ runs the applet: `<cheerpj-applet>`, `<cheerpj-object>` and `<cheerpj-embed>` are all supported.

> **Java applets and Java 8**
>
> Applets run on Java 8 only. cheerpjInit() uses Java 8 when no version is given, so do not set the version option on a page with applets.

## 4. Host your page

The final project directory looks like this:

```plaintext
└── my-project
    ├── index.html
    ├── my_application_archive.jar
    └── lib
        └── my_dependency.jar
```

Go to the project directory and serve it with an HTTP server, such as http-server:

```sh
cd my-project
npx http-server -p 8080
```

Open `http://localhost:8080` in the browser. CheerpJ shows loading messages, then the application’s windows or the applet. The first start downloads the parts of the Java runtime the application needs, so it is slower than later starts.

> **Info**
>
> Opening the page directly from disk (a file:// URL) does not work. The server must support HTTP Range requests: npx http-server and npx serve do, Python’s http.server does not. See basic server setup, and use HTTPS in production.

If the application does not start, check in the browser developer tools’ Network tab that every JAR downloads. A 404 means a JAR is missing from the project directory or its path is wrong.

## Further reading

To learn more about running standalone applications and applets with CheerpJ, see the dedicated getting started pages, or the [JNLP tutorial](https://cheerpj.com/docs/tutorials/jnlp.md), which runs a real JNLP application and a JNLP applet:

[Application](https://cheerpj.com/docs/getting-started/Java-app.md)

[Applet](https://cheerpj.com/docs/getting-started/Java-applet.md)
