Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Guacamole
✓ import Guacamole from 'guacamole-common-js';
✗ 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)
✓ const Guacamole = require('guacamole-common-js');
✗ 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.
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); };
Debug
Known issues
deprecatedThe previous npm package `padarom-guacamole-common-js` has been deprecated in favor of `guacamole-common-js`.fixMigrate your `package.json` dependency from `padarom-guacamole-common-js` to `guacamole-common-js`.
affects: All versions of `padarom-guacamole-common-js`.
gotchaThis 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.fixAlways 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.
affects: >=1.0.0
gotchaThe 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`.fixWhen 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.
affects: All versions
gotchaThis 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.fixAccess all classes and functions (e.g., `Client`, `HTTPTunnel`, `Keyboard`) as properties of the `Guacamole` object (e.g., `Guacamole.Client`).
affects: All versions
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'Client') / Guacamole is not defined
Attempting to access `Guacamole.Client` or other properties when the `Guacamole` object itself is not properly imported or available in the scope.
fixEnsure `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
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.
fixVerify 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. Audit
Dependencies
No dependency data recorded yet.