{"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,"search_vec":"'1.0.0':125 '1.5.0':62 'abstract':148 'adjust':134 'align':107 'apach':15,114 'append':121 'b':126 'browser':45,159 'bundl':96 'client':3,12,74,146,163 'client-sid':73 'clientless':21 'combin':86 'common':6,167 'communic':46 'communiti':66 'community-maintain':65 'connect':36 'consumpt':82 'core':10 'current':59 'dedic':162 'denot':128 'desktop':23,35,154,171 'direct':41 'distribut':80 'draw':149 'e.g':124 'effici':53 'enabl':151 'encapsul':26 'establish':31 'experi':155 'fix':132 'fork':68,130 'fork-specif':129 'function':29 'gateway':24 'guac':169 'guacamol':1,5,16,49,72,115,144,166 'guacamole-common-j':4 'http':54 'integr':98 'interact':152 'javascript':2,11,76,91,165 'js':7,168 'layer':150 'letter':123 'librari':13,136 'maintain':67 'manag':33 'might':120 'minifi':88 'minor':117 'modern':100 'necessari':28 'npm':84 'number':110 'offici':71 'open':19 'open-sourc':18 'packag':58 'patch':118 'prepar':78 'primari':138 'project':102,116 'protocol':145 'provid':142 'pure':156 'rdp':38,173 'relev':90 'remot':22,34,153,170 'requir':161 'role':139 'server':50 'side':75 'simplifi':97 'singl':95 'softwar':164 'sourc':20,92 'specif':57,77,131 'ssh':39 'strive':105 'telnet':40 'tunnel':55 'upstream':113 'version':61,109,119 'via':51 'vnc':37,172 'web':44,101 'within':42 'without':160","created_at":"2026-04-19T16:49:20.586159+00:00","updated_at":"2026-04-19T16:49:20.586159+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://guacamole.apache.org","github":"https://github.com/padarom/guacamole-common-js","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/guacamole-common-js","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}