# Install the SDK in Node or React

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

Install @bsv/sdk in a Node (CommonJS or ESM) or React project.

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

Add `@bsv/sdk` to a Node project, with ES modules or CommonJS, or to a React app built with Vite, and confirm it loads with a script that hashes a string. Do this before you write SDK code in a project, or when you need to check that your toolchain resolves the package. The check runs offline, with no wallet, no key and no network call, so it proves that the package loads and nothing more. This page was written against `@bsv/sdk` 4.0.1, TypeScript 7.0.2 and Vite 8.3.5.

## Before you begin

You need:

- Node.js 22 or newer. The package declares `"node": ">=22"` in its `engines` field. The React with Vite tab needs Node.js 22.12 or newer, which Vite 8 requires.
- A project folder with a `package.json`. For a new Node project, run `npm init -y`. For a new React app, run `npm create vite@latest my-app -- --template react-ts --no-interactive`, then `npm install` in the `my-app` folder.

## How it works

`@bsv/sdk` has no runtime dependencies, so the install adds one package. It ships the same code as an ES module build and a CommonJS build, with TypeScript declarations for each. The `exports` field of its `package.json` picks the build from the way your code loads it:

<BlueTable>

| Your code | Build it loads |
| --- | --- |
| `import` in Node, or a bundler such as Vite | `dist/esm` |
| `require` in Node | `dist/cjs` |

</BlueTable>

The package name and the exported names are the same in every case. Only the import syntax changes.

## Install the package

The first step is to add the package from npm. In a terminal, in the folder that holds your `package.json`, run:

```bash
npm install @bsv/sdk
```

In a new Node project, npm adds one package:

```text
added 1 package, and audited 2 packages in 6s

found 0 vulnerabilities
```

To see the installed version, run `npm ls @bsv/sdk` in the same folder. Its last line reads `└── @bsv/sdk@4.0.1`, or the version you installed.

## Load the SDK in your project

With the package installed, load it the way your project loads modules. Each tab hashes the text `hello BSV` with SHA-256. `Hash.sha256` returns the hash as a `number[]` of bytes, and `Utils.toHex` turns it into a hexadecimal string. The hash is the same on every machine, so you can compare yours with the one shown:

**Node, ES modules**

**1. Set the module type**

Mark the project as ES modules, from the project folder:

```bash
npm pkg set type=module
```

In npm 11, `npm init -y` writes `"type": "commonjs"`, and with that value Node rejects `import` in a `.js` file.

**2. Write the script**

Create `index.js` in the project folder:

```javascript index.js
import { Hash, Utils } from '@bsv/sdk'

const digest = Hash.sha256('hello BSV', 'utf8')
console.log(Utils.toHex(digest))
```

**3. Run the script**

Run it with Node:

```bash
node index.js
```

Node prints the hash:

```text
cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6
```

**Node, CommonJS**

**1. Write the script**

Create `index.js` in a project whose `package.json` has `"type": "commonjs"` or no `type` field:

```javascript index.js
const { Hash, Utils } = require('@bsv/sdk')

const digest = Hash.sha256('hello BSV', 'utf8')
console.log(Utils.toHex(digest))
```

**2. Run the script**

Run it with Node:

```bash
node index.js
```

Node prints the hash:

```text
cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6
```

**Node, TypeScript**

**1. Add the compiler**

Install TypeScript and the Node type definitions as development dependencies:

```bash
npm install -D typescript @types/node
```

**2. Configure the compiler**

Create `tsconfig.json` in the project folder:

```json tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "types": ["node"]
  },
  "include": ["src"]
}
```

Three settings matter for the SDK:

- `"moduleResolution": "nodenext"` reads the `exports` field of the package. The values `node16` and `bundler` read it too.
- `"types": ["node"]` loads the Node type definitions. The SDK declarations use the `Buffer` type, and without this line TypeScript 7 stops with an error.
- `"module": "nodenext"` makes the compiler write `import` when `package.json` has `"type": "module"` and `require` when it has `"type": "commonjs"`, so the same source works for both formats.

**3. Write the script**

Add the script in `src/index.ts`:

```typescript src/index.ts
import { Hash, Utils } from '@bsv/sdk'

const digest: number[] = Hash.sha256('hello BSV', 'utf8')
console.log(Utils.toHex(digest))
```

**4. Compile and run**

Compile the project, then run the output:

```bash
npx tsc
node dist/index.js
```

`tsc` prints nothing when it succeeds, and Node prints the hash:

```text
cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6
```

**React with Vite**

For a Next.js app, [Integrate the BSV blockchain with web frameworks](https://bsvblockchain.com/docs/guides/app-frameworks/) shows the setup.

**1. Write the component**

Replace the contents of `src/App.tsx` in your Vite project. The component hashes the text of the field on every change:

```tsx src/App.tsx
import { useState } from 'react'
import { Hash, Utils } from '@bsv/sdk'

export default function App() {
  const [text, setText] = useState('hello BSV')
  const digest = Utils.toHex(Hash.sha256(text, 'utf8'))

  return (
    <main>
      <h1>@bsv/sdk in React</h1>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <p>SHA-256: {digest}</p>
    </main>
  )
}
```

**2. Build the app**

From the project folder, run the production build:

```bash
npm run build
```

Vite bundles the ES module build of the SDK. The end of the output looks like this, with other file names, sizes and times:

```text
✓ 232 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                   0.46 kB │ gzip:  0.29 kB
dist/assets/index-DGNrK5qb.css    1.78 kB │ gzip:  0.81 kB
dist/assets/index-RoBcJqE5.js   249.80 kB │ gzip: 79.84 kB

✓ built in 665ms
```

This example builds with no polyfill and no change to `vite.config.ts`.

**3. Open the page**

Start the development server with `npm run dev` and open the local address it prints. The page shows the field with `hello BSV` and this line:

```text
SHA-256: cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6
```

A matching hash means the SDK is installed and your project resolves it.

## Troubleshooting

**Node rejects the import statement**

Node stops with `SyntaxError: Cannot use import statement outside a module`. The nearest `package.json` has `"type": "commonjs"`, so Node reads `index.js` as CommonJS. Run `npm pkg set type=module`, or use `require` as in the CommonJS tab.

**TypeScript cannot find the Buffer type**

`tsc` stops with `Cannot find name 'Buffer'` in `BinaryFetchClient.d.ts` under `node_modules/@bsv/sdk/dist`. The SDK declarations use the Node `Buffer` type, and the compiler did not load the Node type definitions. Install `@types/node` and add `"types": ["node"]` to `compilerOptions` in `tsconfig.json`.

## Next steps

With the SDK installed, build it into a web app or start from a project that already uses it:

- [Integrate the BSV blockchain with web frameworks](https://bsvblockchain.com/docs/guides/app-frameworks/)
- [Start a project from a template](https://bsvblockchain.com/docs/get-started/project-starter/)