BSV blockchainBSV blockchain

Install the SDK in Node or React

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:

Your codeBuild it loads
import in Node, or a bundler such as Vitedist/esm
require in Nodedist/cjs

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:

npm install @bsv/sdk

In a new Node project, npm adds one package:

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:

Set the module type

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

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.

Write the script

Create index.js in the project folder:

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

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

Run the script

Run it with Node:

node index.js

Node prints the hash:

cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6

Write the script

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

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

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

Run the script

Run it with Node:

node index.js

Node prints the hash:

cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6

Add the compiler

Install TypeScript and the Node type definitions as development dependencies:

npm install -D typescript @types/node

Configure the compiler

Create tsconfig.json in the project folder:

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.

Write the script

Add the script in src/index.ts:

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

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

Compile and run

Compile the project, then run the output:

npx tsc
node dist/index.js

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

cf2ca7aec45d699b3f52287c42bef1745cf441e2cc5f32dca9860ae7ab0cebf6

For a Next.js app, Integrate the BSV blockchain with web frameworks shows the setup.

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:

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>
  )
}

Build the app

From the project folder, run the production build:

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:

✓ 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.

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:

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: