Documentation

Node.js vs Browser Usage

Node.js Setup

Requirements

  • Node.js: Version 24.0.0 or higher.
  • ESM only: The library is published as ES modules.

To verify your current Node.js version, run the following command. If your version is below the minimum requirement, download and install the latest release from the official Node.js website.

bash
Check Node.js version
node --version  # Should be >= v24.0.0

Project Structure

The recommended basic Node.js project should follow this folder structure:

my-opnet-app/ src/ index.ts package.json tsconfig.json

Configuration

The minimal package.json file should contain the following configuration:

json
Minimal package.json
{
    "type": "module",
    "engines": {
        "node": ">=24.0.0"
    },
    "dependencies": {
        "@btc-vision/transaction": "^1.8.0",
        "@btc-vision/bitcoin": "^7.0.0"
    },
    "devDependencies": {
        "typescript": "^5.9.3"
    }
}

Versions listed were current at the time of writing. Update to the latest versions as needed.

Verify Installation

Create a basic test script in src/index.ts.

typescript
index.ts
import { Mnemonic, Wallet, TransactionFactory } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

// Generate a mnemonic and derive a wallet
const mnemonic = Mnemonic.generate();
const wallet = mnemonic.derive(0);

console.log('P2TR address:', wallet.p2tr);
console.log('P2WPKH address:', wallet.p2wpkh);
console.log('Quantum public key length:', wallet.quantumPublicKey.length, 'bytes');

// Confirm TransactionFactory is available
const factory = new TransactionFactory();
console.log('TransactionFactory ready');

Then run it:

bash
Run the index.ts file
npx tsx src/index.ts

The output window should display the logged messages.

Browser Setup

The library ships pre-built browser bundles at @btc-vision/transaction/browser. These bundles include all necessary polyfills for Node.js APIs (Buffer, crypto, stream, zlib).

Using Vite

Required Dependencies for Vite Builds

typescript
Install using npm
npm install -D vite vite-plugin-node-polyfills buffer stream-browserify browserify-zlib process

Vite Configuration File

Create or update a vite.config.ts file with the following configuration.

typescript
vite.config.ts
// vite.config.ts
import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import { resolve } from 'path';

export default defineConfig({
    build: {
        target: 'esnext',
    },
    resolve: {
        alias: {
            // Point to the browser builds of BTC Vision packages
            crypto: resolve(__dirname, 'node_modules/@btc-vision/transaction/browser/polyfills.js'),
            '@btc-vision/bitcoin': resolve(
                __dirname,
                'node_modules/@btc-vision/bitcoin/browser/index.js',
            ),
            '@btc-vision/bip32': resolve(
                __dirname,
                'node_modules/@btc-vision/bip32/src/cjs/index.cjs',
            ),
        },
    },
    define: {
        'process.env.NODE_ENV': JSON.stringify('production'),
        global: 'globalThis',
    },
    plugins: [
        nodePolyfills({
            globals: {
                Buffer: true,
                global: true,
                process: true,
            },
            exclude: [
                'crypto', 'fs', 'path', 'os', 'http', 'https',
                'net', 'tls', 'dns', 'child_process', 'zlib', 'vm',
            ],
        }),
    ],
});

Importing in Browser Code

typescript
Import for browser
// Use the explicit browser entry point
import { TransactionFactory, Mnemonic } from '@btc-vision/transaction/browser';

Or rely on the conditional exports map. Bundlers that support the "browser" condition will automatically resolve to the browser build.

typescript
Import for browser
// Bundler auto-resolves to browser/index.js when targeting browsers
import { TransactionFactory, Mnemonic } from '@btc-vision/transaction';

Package Exports

The library uses Node.js conditional exports to serve the correct build for each environment.

Export Path Description
@btc-vision/transaction Main entry -> auto-selects Node.js or browser build
@btc-vision/transaction/browser Explicit browser entry point
@btc-vision/transaction/browser/noble-curves Browser build of @noble/curves
@btc-vision/transaction/browser/noble-hashes Browser build of @noble/hashes
@btc-vision/transaction/browser/btc-vision-bitcoin Browser build of @btc-vision/bitcoin
@btc-vision/transaction/browser/btc-vision-bip32 Browser build of @btc-vision/bip32
@btc-vision/transaction/browser/btc-vision-post-quantum Browser build of post-quantum crypto
@btc-vision/transaction/browser/bip39 Browser build of BIP39 mnemonic library
@btc-vision/transaction/browser/polyfills Node.js polyfills (Buffer, process, crypto)
@btc-vision/transaction/browser/vendors Bundled third-party vendor code
@btc-vision/transaction/browser/bitcoin-utils Browser build of Bitcoin utilities
@btc-vision/transaction/browser/scure-base Browser build of @scure/base
@btc-vision/transaction/browser/pako Browser build of pako (zlib compression)

Conditional Export Resolution Flow

Conditional Export Resolution import from '@btc-vision/transaction' Environment? browser condition browser/index.js node condition build/index.js default build/index.js
On this page