{"id":12730,"library":"guacamole-common-js","title":"Guacamole JavaScript Client","description":"guacamole-common-js is the core JavaScript client library for Apache Guacamole, an open-source, clientless remote desktop gateway. It encapsulates the necessary functionalities to establish and manage remote desktop connections (VNC, RDP, SSH, Telnet) directly within a web browser, communicating with a Guacamole server via an efficient HTTP tunnel. This specific package, currently at version 1.5.0, is a community-maintained fork of the official Guacamole client-side JavaScript, specifically prepared for distribution and consumption through npm. It combines and minifies all relevant JavaScript sources into a single bundle, simplifying integration into modern web projects. While it strives to align its version numbers with the upstream Apache Guacamole project, minor patch versions might append a letter (e.g., `1.0.0-b`) to denote fork-specific fixes or adjustments. The library's primary role is to provide the Guacamole protocol client and abstract drawing layers, enabling interactive remote desktop experiences purely in a browser without requiring dedicated client software.","status":"active","version":"1.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/padarom/guacamole-common-js","tags":["javascript","guacamole","common","js","guac","remote","desktop","vnc","rdp"],"install":[{"cmd":"npm install guacamole-common-js","lang":"bash","label":"npm"},{"cmd":"yarn add guacamole-common-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add guacamole-common-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library provides a single default export named `Guacamole`, which is a global object containing all client-side classes and utilities.","wrong":"import { Guacamole } from 'guacamole-common-js';","symbol":"Guacamole","correct":"import Guacamole from 'guacamole-common-js';"},{"note":"For CommonJS environments, the entire library is exported as the default module object.","wrong":"const { Guacamole } = require('guacamole-common-js');","symbol":"Guacamole (CommonJS)","correct":"const Guacamole = require('guacamole-common-js');"},{"note":"When included directly in a browser via a `<script>` tag, the `Guacamole` object is exposed globally.","symbol":"Guacamole global","correct":"// Guacamole will be available as a global variable if loaded via a <script> tag\n// window.Guacamole.Client"}],"quickstart":{"code":"import Guacamole from 'guacamole-common-js';\n\n// Assumes a 'display' div exists in your HTML:\n// <div id=\"display\"></div>\n\n// Create a Guacamole HTTP tunnel. Replace '/guacamole/tunnel' with your server's tunnel endpoint.\n// This is the primary communication mechanism with the Guacamole server.\nconst tunnel = new Guacamole.HTTPTunnel(\"/guacamole/tunnel\");\n\n// Instantiate the Guacamole client, passing the tunnel\nconst client = new Guacamole.Client(tunnel);\n\n// Get the display element from the client\nconst displayElement = client.getDisplay().getElement();\n\n// Append the Guacamole display to your designated HTML element\ndocument.getElementById(\"display\").appendChild(displayElement);\n\n// Handle client state changes (e.g., connection status)\nclient.onstatechange = function(state) {\n    if (state === Guacamole.Client.State.DISCONNECTED) {\n        console.log(\"Disconnected from Guacamole server.\");\n    } else if (state === Guacamole.Client.State.CONNECTED) {\n        console.log(\"Connected to Guacamole server.\");\n    }\n};\n\n// Handle errors from the Guacamole client\nclient.onerror = function(error) {\n    console.error(\"Guacamole client error:\", error);\n    alert(\"Connection error: \" + error.message);\n};\n\n// Finally, connect to the Guacamole server\nclient.connect();\n\n// To send user input (keyboard/mouse), you would typically use:\n// const keyboard = new Guacamole.Keyboard(document);\n// const mouse = new Guacamole.Mouse(displayElement);\n// mouse.onmouseup = function(state) { client.sendMouseState(state); };\n// keyboard.onkeydown = function(keysym) { client.sendKeyEvent(keysym, true); };","lang":"javascript","description":"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."},"warnings":[{"fix":"Migrate your `package.json` dependency from `padarom-guacamole-common-js` to `guacamole-common-js`.","message":"The previous npm package `padarom-guacamole-common-js` has been deprecated in favor of `guacamole-common-js`.","severity":"deprecated","affected_versions":"All versions of `padarom-guacamole-common-js`."},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Access all classes and functions (e.g., `Client`, `HTTPTunnel`, `Keyboard`) as properties of the `Guacamole` object (e.g., `Guacamole.Client`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to access `Guacamole.Client` or other properties when the `Guacamole` object itself is not properly imported or available in the scope.","error":"TypeError: Cannot read properties of undefined (reading 'Client') / Guacamole is not defined"},{"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.","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.","error":"Failed to load resource: the server responded with a status of 404 (Not Found) for /guacamole/tunnel"}],"ecosystem":"npm"}