{"record":{"id":"c413de867ca19e4b","repo":"hcengineering/platform","slug":"the-ws-package-is-required-for-nodewebsocketfact","errorCode":null,"errorMessage":"The \"ws\" package is required for NodeWebSocketFactory. ","messagePattern":"The \"ws\" package is required for NodeWebSocketFactory\\. ","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"foundations/core/packages/api-client/src/socket/node.ts","lineNumber":26,"sourceCode":"// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n//\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//\n\nimport { type ClientSocket, type ClientSocketFactory } from '@hcengineering/client'\n\n/** @public */\nexport const NodeWebSocketFactory: ClientSocketFactory = (url: string): ClientSocket => {\n  // We need to override default factory with 'ws' one.\n  // eslint-disable-next-line\n  let WebSocket\n  try {\n    WebSocket = require('ws')\n  } catch (error) {\n    throw new Error('The \"ws\" package is required for NodeWebSocketFactory. ')\n  }\n  type WebSocketData = Parameters<typeof ws.on>[1]\n\n  const ws = new WebSocket(url)\n\n  const client: ClientSocket = {\n    get readyState (): number {\n      return ws.readyState\n    },\n\n    send: (data: string | ArrayBufferLike | Blob | ArrayBufferView): void => {\n      if (data instanceof Blob) {\n        void data.arrayBuffer().then((buffer) => {\n          ws.send(buffer)\n        })\n      } else {\n        ws.send(data)\n      }","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/core/packages/api-client/src/socket/node.ts#L8-L44","documentation":"NodeWebSocketFactory lazily requires the 'ws' package to create WebSocket connections in Node.js (browsers have a built-in WebSocket, Node does not). If 'ws' is not installed or cannot be resolved, the factory throws this Error immediately when a socket connection is attempted.","triggerScenarios":"Using PlatformWorkerWebSocketFactory / NodeWebSocketFactory in a Node environment where the 'ws' dependency is absent — e.g. a minimal install, pnpm strict node_modules hoisting issues, bundlers (webpack/esbuild) that didn't mark 'ws' as external, or running from a deployment image that pruned devDependencies.","commonSituations":"Docker image built with npm ci --omit=dev while 'ws' ended up a transitive/dev dep; serverless bundle missing node_modules; monorepo where @hcengineering/api-client is linked without its peer 'ws'; upgrading packages and dropping 'ws' from package.json.","solutions":["npm install ws (and @types/ws for TypeScript) in the project that uses the api-client.","If bundling, mark 'ws' as external (webpack: externals; esbuild: --external:ws) and ship it in node_modules.","If deploying a Docker image, ensure production dependencies include ws (check node_modules/ws exists in the image).","Alternatively provide your own WebSocketFactory that supplies a WebSocket implementation available in your runtime."],"exampleFix":"// before\nconst client = new PlatformClient(url, workspace, token) // throws at connect: The \"ws\" package is required...\n// after\n// 1) npm install ws\n// 2) or supply an explicit factory\nimport ws from 'ws'\nconst client = new PlatformClient(url, workspace, token, undefined, {\n  socketFactory: (url) => new WebSocket(url) // your own impl backed by 'ws'\n})","handlingStrategy":"validation","validationCode":"// Run before creating a Node WebSocket client\nlet wsAvailable = false\ntry { require.resolve('ws'); wsAvailable = true } catch {}\nif (!wsAvailable) {\n  throw new Error('Install the \"ws\" package: npm install ws')\n}","typeGuard":null,"tryCatchPattern":"try {\n  const client = createNodeWebSocketFactory(url)\n} catch (e) {\n  if (e instanceof Error && e.message.includes('\"ws\" package is required')) {\n    // surface a clear install instruction to the operator\n    console.error('Missing dependency: run `npm install ws @types/ws`')\n  }\n  throw e\n}","preventionTips":["Add 'ws' (and '@types/ws') to package.json dependencies of every service using the api-client in Node.","Verify node_modules/ws exists in your Docker/CI image after npm ci --omit=dev.","When bundling, mark 'ws' as external so it is not tree-shaken or inlined incorrectly.","Smoke-test socket connectivity in deployment pipelines."],"tags":["nodejs","websocket","missing-dependency","ws"],"backgroundTag":"missing-peer-dependency","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}