BigBlocks

Production-ready Bitcoin UI components for React applications. Copy, paste, customize.

What is BigBlocks?

A comprehensive Bitcoin development ecosystem featuring beautifully designed, accessible UI components that you can copy and paste into your apps. Built with TypeScript, shadcn/ui, and BSV blockchain integration.

This is NOT a traditional component library. It's a collection of copy-and-paste components that you own. Use the CLI to selectively add components to your project, or install the full library via npm.

Complete ecosystem includes: Component library, comprehensive documentation, theme gallery, CLI tools, VS Code extension, and MCP server integration - all available at bigblocks.dev.

Features

• 🔐 Authentication - Complete Bitcoin wallet authentication flows
• 💬 Social - Posts, likes, follows, messaging on Bitcoin
• 💰 Wallet - Send BSV, view balances, manage tokens
• 🏪 Market - Create and purchase listings
• 👤 Profile - User profiles and identity management
• 🎨 Accessible - Built with shadcn/ui for accessibility
• 🚀 Customizable - Copy to your project and make it yours
• ⚡ Modern - TypeScript, React 18+, ES modules
• 🌐 Framework Agnostic - Works with Express, Next.js, Astro, any framework!

📚 Documentation

→ Full Documentation - Complete component documentation, guides, and examples → CLI Documentation - Complete CLI command reference and usage guide

🚀 Quick Start

→ Complete Quick Start Guide - Comprehensive setup guide with detailed examples

⚠️ Required: shadcn/ui Setup

BigBlocks extends shadcn/ui and requires it as a dependency. Install shadcn/ui first:

# 1. Install shadcn/ui (Required)
npx shadcn@latest init

# 2. Verify it works
npx shadcn@latest add button

Method 1: CLI (Recommended)

Use the CLI to selectively install only the components you need:

npx bigblocks@latest init

This will set up your project and guide you through the installation process.

# Browse all available components
npx bigblocks list

# Add specific components
npx bigblocks add auth-flow
npx bigblocks add social-feed wallet-overview

CLI creates bigblocks.config.json and copies components to your project. You own the code.

Method 2: NPM Package

⚠️ Don't mix approaches! Choose either CLI (copy-paste) OR npm (library). Don't use both.

Install the complete library:

# Just Authentication (Recommended Start)
npm install bigblocks

# With Wallet/Social Features
npm install bigblocks @tanstack/react-query

# Everything (All Features)
npm install bigblocks @tanstack/react-query js-1sat-ord sigma-protocol

💡 Which method to choose?

• CLI: Best for production - only includes components you use, keeps bundle small
• NPM: Great for prototyping - get everything at once

📚 Documentation

• Quick Start Guide - Complete setup instructions
• Component Registry - All available components
• Examples - Real-world usage examples

📝 Usage Examples

CLI Usage (Copy-Paste Components)

After running npx bigblocks init and npx bigblocks add auth-flow:

// BigBlocks uses shadcn/ui components - ensure you have Tailwind CSS configured
import { BigBlocksThemeProvider, BitcoinAuthProvider } from 'bigblocks';
import { AuthFlowOrchestrator } from './components/bigblocks/AuthFlowOrchestrator';

function App() {
  return (
    <BigBlocksThemeProvider>
      <BitcoinAuthProvider>
        <AuthFlowOrchestrator
          flowType="unified"
          onSuccess={(user) => {
            console.log('User authenticated:', user);
          }}
        />
      </BitcoinAuthProvider>
    </BigBlocksThemeProvider>
  );
}

NPM Package Usage

If you installed via npm:

// BigBlocks uses shadcn/ui components - ensure you have Tailwind CSS configured
import { BigBlocksThemeProvider, BitcoinAuthProvider, AuthFlowOrchestrator } from 'bigblocks';

function App() {
  return (
    <BigBlocksThemeProvider>
      <BitcoinAuthProvider>
        <AuthFlowOrchestrator
          flowType="unified"
          onSuccess={(user) => {
            console.log('User authenticated:', user);
          }}
        />
      </BitcoinAuthProvider>
    </BigBlocksThemeProvider>
  );
}

Social Media App

import { PostButton, SocialFeed, LikeButton } from 'bigblocks';

function SocialApp() {
  return (
    <div>
      <PostButton onSuccess={() => console.log('Posted!')} />
      <SocialFeed />
    </div>
  );
}

Bitcoin Wallet

import { WalletOverview, SendBSVButton } from 'bigblocks';

function WalletApp() {
  return (
    <div>
      <WalletOverview />
      <SendBSVButton 
        onSuccess={(txid) => console.log('Sent!', txid)}
      />
    </div>
  );
}

Framework-Agnostic Authentication (NEW!)

Use BigBlocks with any JavaScript framework:

// Express.js
import { createExpressBigBlocks } from 'bigblocks/express';
app.use('/api/auth', createExpressBigBlocks().handler);

// Next.js
import { createNextJSBigBlocks } from 'bigblocks/nextjs';
export const { GET, POST } = createNextJSBigBlocks();

// Astro
import { createAstroBigBlocks } from 'bigblocks/astro';
export const { GET, POST } = createAstroBigBlocks();

→ Framework Usage Guide

📦 Available Components (98 Total)

BigBlocks includes 98 production-ready React components across all Bitcoin development needs:

📊 Component Count: Run bun run count-components to get the latest accurate count from the registry. Use bigblocks count for detailed breakdowns by category.

🔐 Authentication (6 components)

• AuthButton - Main authentication button

• LoginForm - Bitcoin wallet login form

• SignupFlow - New user registration flow

• OAuthRestoreFlow - OAuth wallet restoration

• AuthFlowOrchestrator - Complete authentication orchestrator

💬 Social Features (9 components)

• PostButton - Create posts on Bitcoin
• SocialFeed - Display social media feed
• LikeButton - Like posts on the network
• FollowButton - Follow other users
• MessageDisplay - Display messages
• PostCard - Individual post display
• FriendsDialog - Friends management
• CompactPostButton - Compact post creation
• CompactMessageButton - Compact messaging

💰 Wallet Components (8 components)

• WalletOverview - Complete wallet dashboard
• SendBSVButton - Send Bitcoin transactions
• TokenBalance - Display token balances
• DonateButton - Donation functionality
• Plus compact/quick variants for each

👤 Profile Management (8 components)

• ProfileDropdownMenu - Complete user menu with wallet & themes
• ProfileCard - Display user profile information
• ProfileEditor - Edit profile details
• ProfileSwitcher - Switch between multiple profiles
• ProfileViewer - View profile details
• ProfileManager - Manage multiple profiles
• ProfilePopover - Profile info popover
• ProfilePublisher - Publish profiles to blockchain

🏪 Market Components (6 components)

• MarketTable - Display marketplace listings
• CreateListingButton - Create new listings
• BuyListingButton - Purchase items
• Plus compact/quick variants for each

🎨 UI Components (14 components)

• PasswordInput - Secure password field
• LoadingButton - Button with loading states
• ErrorDisplay - Error message display
• BitcoinAvatar - User avatars
• TransactionProgress - Blockchain transaction status
• ErrorRecovery - Smart error handling
• Modal - Dialog modals
• QRCodeRenderer - QR code display
• CodeBlock - Code syntax highlighting
• WarningCard - Warning messages
• StepIndicator - Multi-step processes
• DecorativeBox - Styled containers
• BitcoinImage - Bitcoin-themed images
• Plus layout components

🔧 Additional Categories

• Backup/Recovery (8 components) - BackupImport, BackupDownload, MnemonicDisplay, IdentityGeneration, FileImport, DeviceLinkQR, MemberExport, CloudBackupManager
• Layout Components (6 components) - AuthLayout, CenteredLayout, AuthCard, LoadingLayout, ErrorLayout, SuccessLayout
• Wallet Integration (5 components) - OAuthProviders, OAuthConflictModal, OAuthRestoreForm, YoursWalletConnector, HandCashConnector
• Developer Tools (4 components) - ArtifactDisplay, ShamirSecretSharing, Type42KeyDerivation, KeyManager
• BAP Identity (3 components) - BapKeyRotationManager, BapFileSigner, BapEncryptionSuite
• Providers (3 components) - BitcoinAuthProvider, BigBlocksThemeProvider, BigBlocksQueryProvider
• Droplit Integration (3 components) - TapButton, DataPushButton, DataPushForm

📐 Layout System & Responsive Design (NEW!)

• Intelligent Responsive Components - All components now adapt beautifully to any screen size
• Responsive Design - Mobile-first responsive components
• Centralized Layout Constants - Consistent sizing across all components
• Responsive Utilities - Smart breakpoint system with initial, sm, md, lg values
• 8px Grid System - Harmonious spacing scale
• Container Widths - Responsive pages, cards, modals, popovers, forms
• Layout Dimensions - Adaptive sidebars, panels, headers
• TypeScript Support - Fully typed constants and responsive values
• Mobile-First Design - Optimized for mobile with progressive enhancement

View all components →

🌐 Client-Side Library

Important: BigBlocks is a client-side library. Components require browser APIs for:

• Bitcoin wallet operations
• File handling (backups)
• Cryptographic operations
• Clipboard access

For SSR frameworks, disable server rendering:

• Next.js: Use dynamic imports with ssr: false
• Astro: Use client:only directives
• Remix: Use .client.tsx files

🛠️ CLI Commands

# Initialize BigBlocks
npx bigblocks@latest init

# List all available components
bigblocks list

# Add specific components
bigblocks add auth-flow
bigblocks add social-feed wallet-overview

# Check registry status
bigblocks status

# View documentation
bigblocks docs

🔗 Blockchain Registry (Experimental)

Enable decentralized component fetching from BSV blockchain:

# Set your private key (WIF format)
export BIGBLOCKS_WIF="your-private-key-here"

# Components will now be fetched from both GitHub and blockchain
bigblocks list

⚠️ Experimental Feature: Blockchain registry is currently in development. Components are fetched via MAP protocol queries on BSV blockchain.

🎨 Styling & Theming

BigBlocks uses CSS variables for automatic theme support. Components automatically adapt to theme changes without manual intervention.

Quick Styling Example

// ✅ Good - Automatic theme support
<div style={{
  background: 'var(--gray-1)',
  color: 'var(--accent-9)',
  border: '1px solid var(--gray-7)',
  borderRadius: 'var(--radius-3)',
  padding: 'var(--space-4)'
}}>
  Content adapts to any theme
</div>

// ❌ Avoid - Won't respond to theme changes  
<div style={{
  background: '#ffffff',
  color: '#f7931a'
}}>
  Static colors
</div>

Bitcoin Themes

<BigBlocksThemeProvider defaultTheme="purple">   {/* Purple */}
<BigBlocksThemeProvider defaultTheme="cyberpunk"> {/* Cyberpunk */}
<BigBlocksThemeProvider defaultTheme="ocean">     {/* Ocean */}
<BigBlocksThemeProvider defaultTheme="dark">      {/* Dark Mode */}

🎨 60+ Pre-configured Themes

BigBlocks includes 60+ beautiful theme presets ready to use:

import { BigBlocksThemeProvider, getThemePreset, themeCategories } from 'bigblocks';

// Use a pre-configured theme
<BigBlocksThemeProvider defaultTheme="cyberpunk">
  <App />
</BigBlocksThemeProvider>

// Access theme metadata
const theme = getThemePreset('ocean');
console.log(theme); // { name: 'Ocean', description: 'Cool cyan theme...', accentColor: 'cyan', ... }

// Browse available themes by category
console.log(themeCategories.sophisticated); // ['neo', 'cyberpunk', 'neon', 'noir', ...]
console.log(themeCategories.nature);        // ['forest', 'ocean', 'sunset', 'midnight', ...]
console.log(themeCategories.elegant);       // ['rose', 'lavender', 'emerald', 'sapphire', ...]
console.log(themeCategories.artistic);      // ['vintage', 'sepia', 'monochrome', 'pastel', ...]

Theme Categories:

• Sophisticated (8 themes): Neo, Cyberpunk, Neon, Noir, Aurora, Nebula, Prism, Vortex
• Nature (8 themes): Forest, Ocean, Sunset, Midnight, Dawn, Twilight, Storm, Arctic
• Elegant (8 themes): Rose, Lavender, Emerald, Sapphire, Ruby, Topaz, Onyx, Pearl
• Artistic (8 themes): Vintage, Sepia, Monochrome, Pastel, Vibrant, Minimal, Luxury, Cosmic
• Tweakcn Themes: 37+ themes including modern-minimal, twitter, catppuccin, cyberpunk, claude, vercel, neo-brutalism, and more

📖 Complete Styling Guide →

Layout Constants

BigBlocks provides centralized layout constants for consistent sizing:

import { CONTAINER_WIDTHS, SPACING, HEIGHTS } from 'bigblocks';

// Consistent card widths
<Card style={{ maxWidth: CONTAINER_WIDTHS.CARD_MEDIUM }}>

// Responsive popovers
<Popover.Content style={{ minWidth: CONTAINER_WIDTHS.POPOVER_LARGE }}>

// Harmonious spacing
<Box style={{ padding: SPACING.MD, gap: SPACING.SM }}>

// Fixed header height
<Header style={{ height: HEIGHTS.HEADER_DESKTOP }}>

📐 Layout Constants Guide →

⚠️ Important Implementation Notes

Password Field is ALWAYS Required

A common mistake is labeling the password field as "Password (if encrypted)" or hiding it conditionally. The password field must ALWAYS be shown:

• Encrypted backups: Password decrypts the backup
• Unencrypted backups: Password encrypts for secure storage
• New users: Password encrypts the generated backup

// ❌ WRONG
<PasswordInput label="Password (if encrypted)" />

// ✅ CORRECT  
<PasswordInput label="Password" />

See the Integration Guide for more details.

📚 Documentation & Resources

🌐 Complete Documentation

bigblocks.dev - Your one-stop resource for everything BigBlocks

📖 Key Resources

• 📋 Quick Start Guide - Get up and running in minutes
• 📚 Full Documentation - Comprehensive guides and API references
• 🎨 Component Library - Browse all available components with live examples
• 🎨 Theme Gallery - Explore Bitcoin-inspired color themes
• 🔌 MCP Server - Model Context Protocol integration for AI assistants

🛠️ Developer Tools

• VS Code Extension - Bitcoin development tools for VS Code
• GitHub Repository - Source code and issue tracking

👨‍💻 Contributing

We welcome contributions! BigBlocks is open source and built for the Bitcoin community.

Adding Components

1. Create your component in src/components/
2. Add it to registry/registry.json
3. Add stories for Storybook
4. Submit a pull request

Component Guidelines

• Built with TypeScript and shadcn/ui
• Accessible by default
• Include comprehensive prop documentation
• Follow existing patterns and conventions

Testing

BigBlocks includes comprehensive visual testing using Playwright:

# Run all screenshot tests
bun run test:screenshots

# Run specific test suites
bun run test:screenshots:components  # Component screenshots
bun run test:screenshots:themes      # shadcn/ui theme screenshots
bun run test:screenshots:tweakcn     # Tweakcn theme screenshots

Screenshots are generated in the screenshots/ directory (gitignored) and are useful for:

• Visual regression testing
• Documentation
• Showcasing components with different themes
• Design reviews

See tests/README.md for more information about testing.

🔗 Links

• GitHub Repository
• NPM Package
• Quick Start Guide
• Component Examples

📜 License

MIT © BigBlocks Team

Built with ❤️ for the Bitcoin community

BigBlocks

A comprehensive React component library for Bitcoin authentication, wallet integration, and blockchain interactions.

🚨 IMPORTANT: Backend Setup Required

Before using LoginForm or authentication components, you must implement backend endpoints.

BigBlocks extends NextAuth but requires additional API endpoints. See Backend Setup Guide for complete instructions.

Missing the /api/auth/signin endpoint will cause LoginForm to show "Loading..." forever.

Quick Start

1. Install

npm install bigblocks

2. Setup Backend (REQUIRED)

// app/api/auth/signin/route.ts
export async function POST(request) {
  // Your Bitcoin signature verification here
  // See examples/backend-setup-guide.md for complete code
  return NextResponse.json({ success: true });
}

3. Use Components

import { BitcoinAuthProvider, LoginForm } from 'bigblocks';

<BitcoinAuthProvider config={{ apiUrl: '/api' }}>
  <LoginForm onSuccess={(user) => console.log('Logged in:', user)} />
</BitcoinAuthProvider>

4. Configure Blockchain Services (NEW!)

BigBlocks now supports flexible API key configuration for blockchain services:

// Proxy Mode (Recommended - keeps API keys secure)
<BitcoinAuthProvider config={{
  apiUrl: '/api',
  blockchainService: {
    mode: 'proxy',
    proxy: {
      endpoint: '/api/blockchain',
      headers: { 'Authorization': 'Bearer token' }
    }
  }
}}>

// Client Mode (for development/testing)
<BitcoinAuthProvider config={{
  apiUrl: '/api',
  blockchainService: {
    mode: 'client',
    client: {
      apiKeys: {
        whatsonchain: 'your-api-key',
        taal: 'your-taal-key'
      },
      preferredService: 'whatsonchain'
    }
  }
}}>

📖 API Key Configuration Guide - Complete guide for configuring blockchain services

📖 Backend Setup Guide - Full backend implementation details

Components

// ... existing code ...