Guacamole JavaScript Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'Client') / Guacamole is not defined

  cause Attempting to access `Guacamole.Client` or other properties when the `Guacamole` object itself is not properly imported or available in the scope.
  fix Ensure `import Guacamole from 'guacamole-common-js';` (ESM) or `const Guacamole = require('guacamole-common-js');` (CommonJS) is at the top of your file, or that the library's script tag is loaded before your consuming code in a browser environment.

• Failed to load resource: the server responded with a status of 404 (Not Found) for /guacamole/tunnel

  cause The Guacamole client failed to connect to the server because the specified tunnel endpoint URL is incorrect or the Guacamole server is not running/configured to serve the tunnel.
  fix Verify that your Guacamole server is running and accessible, and that the URL provided to `new Guacamole.HTTPTunnel("/guacamole/tunnel")` accurately reflects your server's Guacamole tunnel endpoint.

Warnings

• deprecated The previous npm package `padarom-guacamole-common-js` has been deprecated in favor of `guacamole-common-js`.
  Fix: Migrate your `package.json` dependency from `padarom-guacamole-common-js` to `guacamole-common-js`.
• gotcha This npm package is a community-maintained fork and its version numbers, while intended to mirror upstream Apache Guacamole, may have minor discrepancies. Patch versions on npm may include a letter suffix (e.g., `1.0.0-b`) not present in upstream.
  Fix: Always check the `guacamole-common-js` npm page for the exact version and any release notes. Do not assume direct version parity with Apache Guacamole releases.
• gotcha The GitHub repository for this fork incorrectly displays `glyptodon/guacamole-client` as its origin due to GitHub's limitations. The actual upstream for Guacamole is `apache/guacamole-client`.
  Fix: When performing `git pull` operations, ensure your remotes are configured to pull from `git@github.com:apache/guacamole-client.git` for upstream updates, not the fork's displayed origin.
• gotcha This library is a pre-bundled JavaScript file. It does not provide individual ES modules or TypeScript definitions for granular imports. All functionalities are exposed through the single `Guacamole` object.
  Fix: Access all classes and functions (e.g., `Client`, `HTTPTunnel`, `Keyboard`) as properties of the `Guacamole` object (e.g., `Guacamole.Client`).

Install

• npm install guacamole-common-js npm
• yarn add guacamole-common-js yarn
• pnpm add guacamole-common-js pnpm

Imports

• Guacamole
  wrong:

  import { Guacamole } from 'guacamole-common-js';

  correct:

  import Guacamole from 'guacamole-common-js';

  The library provides a single default export named `Guacamole`, which is a global object containing all client-side classes and utilities.
• Guacamole (CommonJS)
  wrong:

  const { Guacamole } = require('guacamole-common-js');

  correct:

  const Guacamole = require('guacamole-common-js');

  For CommonJS environments, the entire library is exported as the default module object.
• Guacamole global

  // Guacamole will be available as a global variable if loaded via a <script> tag
  // window.Guacamole.Client

  When included directly in a browser via a `<script>` tag, the `Guacamole` object is exposed globally.

Quickstart

Demonstrates how to install the library, import the Guacamole client, set up an HTTP tunnel, and establish a basic connection to a Guacamole server to display a remote desktop within a specified HTML element.

import Guacamole from 'guacamole-common-js';

// Assumes a 'display' div exists in your HTML:
// <div id="display"></div>

// Create a Guacamole HTTP tunnel. Replace '/guacamole/tunnel' with your server's tunnel endpoint.
// This is the primary communication mechanism with the Guacamole server.
const tunnel = new Guacamole.HTTPTunnel("/guacamole/tunnel");

// Instantiate the Guacamole client, passing the tunnel
const client = new Guacamole.Client(tunnel);

// Get the display element from the client
const displayElement = client.getDisplay().getElement();

// Append the Guacamole display to your designated HTML element
document.getElementById("display").appendChild(displayElement);

// Handle client state changes (e.g., connection status)
client.onstatechange = function(state) {
    if (state === Guacamole.Client.State.DISCONNECTED) {
        console.log("Disconnected from Guacamole server.");
    } else if (state === Guacamole.Client.State.CONNECTED) {
        console.log("Connected to Guacamole server.");
    }
};

// Handle errors from the Guacamole client
client.onerror = function(error) {
    console.error("Guacamole client error:", error);
    alert("Connection error: " + error.message);
};

// Finally, connect to the Guacamole server
client.connect();

// To send user input (keyboard/mouse), you would typically use:
// const keyboard = new Guacamole.Keyboard(document);
// const mouse = new Guacamole.Mouse(displayElement);
// mouse.onmouseup = function(state) { client.sendMouseState(state); };
// keyboard.onkeydown = function(keysym) { client.sendKeyEvent(keysym, true); };