# Supported runtimes

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

What @bsv/sdk needs from a JavaScript runtime, the builds it ships for Node.js, bundlers and script tags, and the errors it raises when the runtime lacks one of them.

import BlueTable from '/snippets/BlueTable.jsx';

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](https://bsvblockchain.com/docs/sdk/typescript/setup/#troubleshooting) explains. The SDK asks the runtime for three things:

<BlueTable>

| Need | What the SDK uses | Used for |
| --- | --- | --- |
| A module loader | An ES module build (`dist/esm`), a CommonJS build (`dist/cjs`) and a UMD (Universal 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 ECIES (Elliptic 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 |

</BlueTable>

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](https://bsvblockchain.com/docs/sdk/defaults/).

## Supported environments

The BSV team declares the supported runtimes of each package in the [stack facts](https://bsv-blockchain.github.io/ts-stack/reference/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](https://bsv-blockchain.github.io/ts-stack/about/versioning/) makes the latest published release the supported version:

<BlueTable>

| 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](https://bsvblockchain.com/docs/sdk/typescript/setup/) |
| 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` |

</BlueTable>

## 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, `import` from `@bsv/sdk` as in a browser app. Workers expose `crypto.getRandomValues` and `fetch` on `self`, which the SDK reads.
- In React Native, a runtime with no `crypto.getRandomValues` needs 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](https://bsvblockchain.com/docs/wallets/bsv-desktop/) or the React Native WebView bridge. See [Connect to a wallet with WalletClient](https://bsvblockchain.com/docs/sdk/typescript/wallet-client/).

## 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 ARC (The 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:

- [Install the SDK in Node or React](https://bsvblockchain.com/docs/sdk/typescript/setup/)
- [SDK default values](https://bsvblockchain.com/docs/sdk/defaults/)
- [Connect to a wallet with WalletClient](https://bsvblockchain.com/docs/sdk/typescript/wallet-client/)