Skip to content

Add introduction and Library Mode reference to "Run a Java Library" #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 27, 2025
Merged

Add introduction and Library Mode reference to "Run a Java Library" #293

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
33b49eb
Added introduction and reference to library-mode docs
rijulshrestha Oct 23, 2025
9880242
Added more context and aligned the formatting with other pages
rijulshrestha Oct 23, 2025
3962390
Revert "Added more context and aligned the formatting with other pages"
rijulshrestha Oct 23, 2025
43925fc
Added more context and aligned the formatting with other pages
rijulshrestha Oct 23, 2025
03996a4
Fixed Lint / Prettier formatting error
rijulshrestha Oct 23, 2025
d0b8f7a
Addressed review feedback; styling consistency and clarify examples
rijulshrestha Oct 25, 2025
70460f8
Fixed Lint / Prettier formatting error
rijulshrestha Oct 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 65 additions & 15 deletions sites/cheerpj/src/content/docs/10-getting-started/02-Java-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,82 @@ title: Run a Java library
description: Use Java classes in JavaScript
---

## 1. Include CheerpJ on your page
CheerpJ can load and run Java libraries directly in the browser, allowing you to call Java classes and methods from JavaScript with no modifications to your original code. This page will help you get started with CheerpJ and show you how to use an existing Java library (`.jar` file) within a web application.

```html
<script src="https://cjrtnc.leaningtech.com/4.2/loader.js"></script>
Java source code is not required to use CheerpJ. If you are using your own library, you should already have its compiled `.jar` file available.

**To get started you will need:**

- Your `.jar` file.
- An HTML file where your Java app will be wrapped.
- A simple HTTP server to test your webpage locally.

## 1. Create a Project Directory

Let's start by creating a project folder where all your files will be. Copy your java and future HTML files here.

```shell
mkdir directory_name
```

## 2. Initialize CheerpJ and load your Java library
## 2. Create a Basic HTML File

Let's create a basic HTML file and include and initialize CheerpJ on your page. The `cheerpjInit` command initialises the CheerpJ runtime environment.

```js
await cheerpjInit();
const cj = await cheerpjRunLibrary("/app/library.jar");
```html title="index.html" {6, 10}
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>CheerpJ Library Mode Test</title>
<script src="https://cjrtnc.leaningtech.com/4.2/loader.js"></script>
</head>
<body>
<script>
await cheerpjInit();
</script>
</body>
</html>
```

> [!help] Don't forget to use the /app/ prefix
> It is common for first-time users to forget to add the prefix “/app/” when passing the JAR location to cheerpJRunLibrary().
## 3. Load and Call the Java Library From Java

This will load `library.jar` from the root of your web server.
Now we can load your Java library by calling `cheerpjRunLibrary` which will load the library from the root of your web server. We are assuming your HTML file and your `.jar` files are under the project directory you just created.

## 3. Call Java from JavaScript
```html title="index.html" {12-15}
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>CheerpJ Library Mode Test</title>
<script src="https://cjrtnc.leaningtech.com/4.2/loader.js"></script>
</head>
<body>
<script>
await cheerpjInit();
// Example classes and methods — replace these with those from your own library
const cj = await cheerpjRunLibrary("/app/library.jar");
const MyClass = await cj.com.library.MyClass;
const obj = await new MyClass();
await obj.myMethod();
Comment on lines +60 to +63
Copy link
Member

@epanholz epanholz Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add a comment here that these are example classes and will look different for whatever library you are using.

</script>
</body>
</html>
```

## 3. Host your page

You can now serve this web page on a simple HTTP server, such as the http-server utility.

```js
const MyClass = await cj.com.library.MyClass;
const obj = await new MyClass();
await obj.myMethod();
```shell
npx http-server -p 8080
```

## The Result

You will see CheerpJ initialize in your browser and load the Java library. Once loaded, the methods from your library can be called directly from JavaScript, just as in the example above. Depending on the size of your library and the optimizations applied, this may take just a few seconds before your code begins executing.

## Further reading

- [Learn more about Library Mode](/docs/guides/library-mode)
- [`cheerpjRunLibrary` reference](/docs/reference/cheerpjRunLibrary)