BigBlocks.dev
Quick Start Guide

Get Started with BigBlocks

Set up your Bitcoin development environment in minutes. This guide covers installation, configuration, and your first component.

Browse 100+ ComponentsView on GitHub

Prerequisites

Required Software

  • Node.js 18+ or Bun (recommended)

    Bun is faster and has better compatibility

  • React 18.x or 19.x

    Both versions are supported

  • TypeScript (optional but recommended)

    Full TypeScript support with auto-complete

Environment Setup

If you're using OAuth providers for backup storage, you'll need:

# .env.local or .env
AUTH_SECRET=your-auth-secret-here
AUTH_GOOGLE_ID=your-google-oauth-id
AUTH_GOOGLE_SECRET=your-google-oauth-secret
AUTH_GITHUB_ID=your-github-oauth-id  
AUTH_GITHUB_SECRET=your-github-oauth-secret

💡 OAuth is optional - used only for encrypted backup storage across devices

Installation

1

Install BigBlocks

bun add bigblocks
Or use npm:
2

Import Required CSS

⚠️ Critical: You must import the CSS file for components to display correctly

// In your app's root layout or _app.tsx
import '@radix-ui/themes/styles.css'
3

Wrap Your App with Providers

import { BitcoinAuthProvider, BitcoinQueryProvider } from 'bigblocks'

export default function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        {/* Your app components */}
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  )
}

💡 The providers enable authentication, data fetching, and theme management

Quick Examples

Basic Authentication

Add Bitcoin-based authentication with a single component:

import { AuthButton } from 'bigblocks'

function MyApp() {
  return (
    <AuthButton 
      onSuccess={(identity) => {
        console.log('Authenticated:', identity.address)
      }}
    >
      Sign In with Bitcoin
    </AuthButton>
  )
}

Send Bitcoin

Enable Bitcoin transactions with built-in UI:

import { SendBSVButton } from 'bigblocks'

function PaymentComponent() {
  return (
    <SendBSVButton 
      recipientAddress="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      amount={1000} // satoshis
      onSuccess={(txid) => {
        console.log('Payment sent:', txid)
      }}
    />
  )
}

Available Components

Explore 100+ production-ready components organized by category:

🔐

Authentication

6

Identity and authentication components

Browse components
💰

Wallet

8

Wallet and payment components

Browse components
💬

Social

9

Social interaction components

Browse components
🛍️

Marketplace

6

Marketplace and trading components

Browse components
👤

Profiles

8

User profile management

Browse components
🎨

UI Components

14

UI primitives and layout components

Browse components
View All Components

Next Steps

📚 Documentation

Deep dive into component APIs, configuration options, and advanced features

🎨 Themes

Customize the look and feel with our professional theme system

💡 Examples

Explore complete example applications built with BigBlocks

Common Issues

Components are unstyled or broken

Make sure you've imported the CSS file:

import '@radix-ui/themes/styles.css'
Missing QueryClient provider error

Wrap your app with BitcoinQueryProvider:

<BitcoinQueryProvider>
  <BitcoinAuthProvider>
    {/* Your app */}
  </BitcoinAuthProvider>
</BitcoinQueryProvider>
OAuth providers not working

Check that you've set up environment variables correctly and that callback URLs match your OAuth app configuration.