Supported runtimes
Use this reference to check what @bsv/sdk needs from the JavaScript environment you target, such as Node.js, a browser app built with a bundler, a plain web page, a worker or React Native, and how to load it there. Read this before you add the SDK to a new kind of project, or when the SDK raises an error about randomness or HTTP that it does not raise elsewhere. This page was written against @bsv/sdk 4.0.1.
What the SDK needs
@bsv/sdk has no runtime dependencies, and its runtime code does not use the Node.js Buffer. Its TypeScript declarations do use the Buffer type, so a TypeScript project needs @types/node and "types": ["node"] in tsconfig.json, even when it targets a browser, as Install the SDK in Node or React explains. The SDK asks the runtime for three things:
| Need | What the SDK uses | Used for |
|---|---|---|
| A module loader | An ES module build (dist/esm), a CommonJS build (dist/cjs) and a UMDUniversal Module Definition, a single file that a page loads with a script tag and that defines a global variable bundle (dist/umd/bundle.js) | Loading the package in any of the environments below |
| Secure random numbers | crypto.getRandomValues of the global object, self or window, or else randomBytes from node:crypto | Generating keys, such as PrivateKey.fromRandom(), and the random values used in encryption, such as ECIESElliptic Curve Integrated Encryption Scheme, which encrypts a message to a public key |
| HTTP requests | The global fetch, or else the node:https module when the code runs as CommonJS | Broadcasting transactions and calling services such as WhatsOnChain |
Building and signing a transaction need neither randomness nor HTTP, but the defaults of two Transaction methods make HTTP calls. With no argument, fee() fetches the current fee rate and verify() checks block headers through a Mainnet chain tracker. On a runtime without HTTP, pass a fixed rate such as fee(new SatoshisPerKilobyte(1)), and call verify('scripts only'), which skips the block header check, or pass a chain tracker of your own. See SDK default values.
Supported environments
The BSV team declares the supported runtimes of each package in the stack facts of the TypeScript stack. For @bsv/sdk they are Node.js 22 or newer, browsers and the UMD bundle, and the support policy makes the latest published release the supported version:
| Environment | How to load it | What to check |
|---|---|---|
| Node.js 22 or newer | import from @bsv/sdk (ES modules) or require('@bsv/sdk') (CommonJS) | The package declares "node": ">=22" in its engines field. See Install the SDK in Node or React |
| Browser app with a bundler, such as Vite | import from @bsv/sdk | The bundler picks the ES module build. No polyfill is needed |
| Web page without a bundler | <script src="bundle.js"> with the file dist/umd/bundle.js of the package | The bundle defines the global bsv, such as bsv.PrivateKey |
Other environments
Web Workers and React Native are not declared runtimes of @bsv/sdk, so test your app there before you rely on it:
- In a module Web Worker,
importfrom@bsv/sdkas in a browser app. Workers exposecrypto.getRandomValuesandfetchonself, which the SDK reads. - In React Native, a runtime with no
crypto.getRandomValuesneeds a polyfill that defines it, imported before@bsv/sdk. For a wallet that runs inside a React Native app, the stack declares a separate package,@bsv/wallet-toolbox-mobile.
To reach the user’s wallet from any of these environments, WalletClient tries its substrates in turn and uses the first that answers, such as the HTTP port of BSV Desktop or the React Native WebView bridge. See Connect to a wallet with WalletClient.
Troubleshooting
Key creation throws because the runtime has no secure random source #
The error is No secure random number generator is available in this environment.. The runtime has no crypto.getRandomValues and no node:crypto, so PrivateKey.fromRandom() and any other call that needs randomness throw this error. In React Native, install a polyfill for crypto.getRandomValues and import it before @bsv/sdk. In other runtimes, check that the global crypto object is not removed or replaced.
Broadcast returns code 500 "Internal Server Error" before reaching the server #
The ARCThe service that receives your transaction and passes it to miners, Teranode and WhatsOnChain broadcaster classes return { status: 'error', code: '500', description: 'Internal Server Error' } when its HTTP request throws before it reaches the server. One cause is a runtime with no fetch that loads the SDK as an ES module, where the node:https fallback is not available. Provide a global fetch, or pass an HTTP client of your own to the broadcaster. The same result can also come from the server itself, so check the network log first.
Related articles
To learn more about setting up the SDK in BSV, review these articles: