Add an NPM Package Dependency

Important constraints

• Golem TypeScript runs inside a QuickJS  WebAssembly runtime, NOT Node.js.
• The runtime implements a broad set of Browser and Node.js APIs. Most packages targeting browsers or standard Node.js APIs will work.
• Packages that use native Node.js C++ addons will not work (no native compilation in WASM).
• node:child_process supports constrained JavaScript and simple npm script execution inside the runtime. It cannot create host processes or run a general shell. node:cluster, node:http2, and node:worker_threads remain unsupported or stubbed.

Supported runtime APIs

• Web Platform APIs: fetch, Headers, Request, Response, FormData, Blob, File, URL, URLSearchParams, console, timers, AbortController, TextEncoder/TextDecoder, Streams (ReadableStream, WritableStream, TransformStream), structuredClone, crypto.randomUUID/crypto.getRandomValues, Event/EventTarget, MessageChannel/MessagePort, Intl
• Node.js modules: node:buffer, node:crypto (hashes, HMAC, ciphers, key generation, sign/verify, DH, ECDH, X509), node:events, node:fs and node:fs/promises (comprehensive filesystem), node:http/node:https (client; servers only through custom HTTP routers with nodeHttpHandler), node:os, node:path, node:perf_hooks, node:process, node:querystring, node:readline, node:sqlite (embedded, requires feature flag), node:stream, node:test, node:timers, node:url, node:util, node:v8, node:vm, node:zlib (gzip, deflate, brotli)
• Not supported: node:net, node:dgram and node:dns. The worker executor refuses WASI sockets by default, so packages that open raw TCP or UDP connections or do DNS lookups through these modules (for example pg, mysql2 or ioredis) fail. Use fetch or node:http for HTTP and golem:rdbms for PostgreSQL and MySQL.

Check the wasm-rquickjs README  for the up-to-date list.

Steps

1. Install the package

   From the project root (where package.json is):

   npm install <package-name>

   For dev-only dependencies (build tools, type definitions):

   npm install --save-dev <package-name>

2. Build to verify

   golem build --yes

   Do NOT run npx rollup or npx tsc directly — always use golem build.

3. If the build or runtime fails

   • Build error: the package may use TypeScript features or module formats incompatible with the Rollup bundling pipeline. Check if the package has an ESM or browser build.
   • Runtime error (X is not defined): the package depends on a Node.js or browser API not available in the QuickJS runtime. Look for an alternative package.

Already available packages

These are already in the project’s package.json — do NOT add them again:

• @golemcloud/golem-ts-sdk — Golem agent framework (defineAgent / method, Standard Schema markers, durability, transactions, RPC)
• rollup with @rollup/plugin-* plugins (dev) — bundling pipeline
• typescript and tslib (dev) — TypeScript compiler and runtime helpers
• @types/node (dev) — Node type definitions

The agent contract is described with a Standard Schema library. zod is used by the default template; valibot, arktype, and effect schemas are also supported — add whichever one your agents use if it is not already present.

HTTP requests

Use the built-in fetch API — it is available globally.

AI / LLM features

Use any third party AI/LLM library from npmjs.com, but it has to only depend on the supported runtime APIs.