{"id":17391,"library":"upgrade","title":"UpgradeJS (minimal WebSocket utilities)","description":"UpgradeJS is a lightweight, low-level Node.js library designed to facilitate direct handling of HTTP upgrade requests, primarily for establishing raw WebSocket connections. It provides utilities for writing WebSocket handshake headers, framing and unmasking WebSocket data. A key limitation of this library is its explicit restriction to WebSocket payloads not exceeding 125 bytes. The package version `1.1.0` is the latest, but the project appears to be unmaintained, with its documentation largely reflecting an earlier `1.0.0` release and no visible recent development or a current active GitHub repository. This library offers a barebones approach, requiring developers to manage many WebSocket protocol details themselves, differentiating it from more feature-rich WebSocket libraries like `ws` or `Socket.IO` that handle framing, fragmentation, and other complexities automatically.","status":"abandoned","version":"1.1.0","language":"javascript","source_language":"en","source_url":"http://github.com/cobbdb/upgrade","tags":["javascript","websocket","http","upgrade","native","simple"],"install":[{"cmd":"npm install upgrade","lang":"bash","label":"npm"},{"cmd":"yarn add upgrade","lang":"bash","label":"yarn"},{"cmd":"pnpm add upgrade","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is CommonJS-only and does not support ES Modules. Use `require()` for all imports.","wrong":"import upgrade from 'upgrade'","symbol":"upgrade","correct":"const upgrade = require('upgrade')"},{"note":"Functions are accessed as properties of the main `upgrade` module object, not as named exports.","wrong":"import { writeHead } from 'upgrade'","symbol":"writeHead","correct":"const upgrade = require('upgrade'); upgrade.writeHead(req, socket);"},{"note":"Functions are accessed as properties of the main `upgrade` module object, not as named exports.","wrong":"import { getData } from 'upgrade'","symbol":"getData","correct":"const upgrade = require('upgrade'); const data = upgrade.getData(buff);"},{"note":"The `send` function (and `getSend`) are core utilities for sending framed WebSocket data.","wrong":"import { send } from 'upgrade'","symbol":"send","correct":"const upgrade = require('upgrade'); upgrade.send('message', socket);"}],"quickstart":{"code":"const http = require('http');\nconst upgrade = require('upgrade');\n\nconst server = http.createServer();\n\nserver.on('upgrade', function (req, socket) {\n    const send = upgrade.getSend(socket);\n    upgrade.writeHead(req, socket);\n\n    socket.on('data', function (buff) {\n        const data = upgrade.getData(buff);\n        console.log('Server received: ' + data);\n        send('Echo: ' + data); // Echo back the received message\n    });\n\n    socket.on('close', () => console.log('Client disconnected.'));\n    socket.on('error', (err) => console.error('Socket error:', err));\n\n    send('Welcome to the Server!');\n});\n\nserver.listen(8000, () => {\n    console.log('WebSocket server listening on port 8000');\n});\n\n// To test, run this in a browser console:\n// const socket = new WebSocket('ws://localhost:8000');\n// socket.onopen = () => { console.log('Socket Open.'); socket.send('Hello Server!'); };\n// socket.onmessage = (evt) => { console.log('Client received: ' + evt.data); };\n// socket.onclose = () => { console.log('Socket Closed.'); };\n// socket.onerror = (err) => { console.error('Socket Error:', err); };\n","lang":"javascript","description":"Demonstrates a basic WebSocket server handling HTTP upgrades, receiving messages, and sending framed responses using UpgradeJS utilities."},"warnings":[{"fix":"Ensure all WebSocket message payloads are 125 bytes or less. For larger payloads, consider a different WebSocket library or implement fragmentation manually.","message":"The `frameData` and `send` functions explicitly do not support payloads larger than 125 bytes. Sending larger data will result in a `RangeError`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Evaluate alternatives like `ws` or `uWS` for actively maintained and feature-rich WebSocket implementations. Use this library only for specific, constrained legacy requirements.","message":"The package appears to be unmaintained. The GitHub repository linked in the npm package is defunct, and there are no signs of active development. This means it may not be compatible with newer Node.js versions or handle modern WebSocket features.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const upgrade = require('upgrade')` to import the module. If using an ES Module project, consider a CommonJS wrapper or a different library.","message":"UpgradeJS is a CommonJS-only module. Attempting to use `import` statements will result in runtime errors in Node.js environments unless transpiled or configured for CJS interop.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Reduce the size of the message payload to 125 bytes or less. This library does not automatically handle WebSocket message fragmentation.","cause":"Attempting to send a WebSocket message with a payload exceeding 125 bytes using `upgrade.frameData()` or `upgrade.send()`.","error":"RangeError: Payload too large for single frame."},{"fix":"Change your import statement to `const upgrade = require('upgrade');` and access functions as properties (e.g., `upgrade.someFunction`).","cause":"Attempting to use ES Module `import { someFunction } from 'upgrade'` syntax with a CommonJS-only module.","error":"SyntaxError: Named export '...' not found. The requested module 'upgrade' does not provide an export named '...'"},{"fix":"Ensure you are using the correct CommonJS import: `const upgrade = require('upgrade');` then access methods as `upgrade.methodName(args)`.","cause":"Incorrectly importing the module (e.g., `const { writeHead } = require('upgrade')` or a failed ESM import) leading to the `upgrade` variable not holding the module object.","error":"TypeError: upgrade.writeHead is not a function (or similar for other methods)"}],"ecosystem":"npm","meta_description":null}