# BigBlocks
Production-ready Bitcoin UI components for React applications. Copy, paste, customize.
[](https://www.npmjs.com/package/bigblocks)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
## 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](https://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](https://bigblocks.dev/docs)** - Complete component documentation, guides, and examples
**[→ CLI Documentation](./docs/CLI.md)** - Complete CLI command reference and usage guide
## 🚀 Quick Start
**[→ Complete Quick Start Guide](https://bigblocks.dev/quickstart)** - Comprehensive setup guide with detailed examples
### ⚠️ Required: shadcn/ui Setup
**BigBlocks extends shadcn/ui and requires it as a dependency.** Install shadcn/ui first:
```bash
# 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:
```bash
npx bigblocks@latest init
```
This will set up your project and guide you through the installation process.
```bash
# 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:
```bash
# 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](./docs/getting-started/quick-start.md) - Complete setup instructions
- [Component Registry](./registry/registry.json) - All available components
- [Examples](./examples/) - Real-world usage examples
## 📝 Usage Examples
### CLI Usage (Copy-Paste Components)
After running `npx bigblocks init` and `npx bigblocks add auth-flow`:
```tsx
// 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 (
{
console.log('User authenticated:', user);
}}
/>
);
}
```
### NPM Package Usage
If you installed via npm:
```tsx
// BigBlocks uses shadcn/ui components - ensure you have Tailwind CSS configured
import { BigBlocksThemeProvider, BitcoinAuthProvider, AuthFlowOrchestrator } from 'bigblocks';
function App() {
return (
{
console.log('User authenticated:', user);
}}
/>
);
}
```
### Social Media App
```tsx
import { PostButton, SocialFeed, LikeButton } from 'bigblocks';
function SocialApp() {
return (
console.log('Posted!')} />
);
}
```
### Bitcoin Wallet
```tsx
import { WalletOverview, SendBSVButton } from 'bigblocks';
function WalletApp() {
return (
console.log('Sent!', txid)}
/>
);
}
```
### Framework-Agnostic Authentication (NEW!)
Use BigBlocks with any JavaScript framework:
```typescript
// 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](./examples/framework-agnostic-usage.md)
## 📦 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 →](./docs/getting-started/quick-start.md#component-examples)
## 🌐 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
```bash
# 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:
```bash
# 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
```tsx
// ✅ Good - Automatic theme support
Content adapts to any theme
// ❌ Avoid - Won't respond to theme changes
Static colors
```
### Bitcoin Themes
```tsx
{/* Purple */}
{/* Cyberpunk */}
{/* Ocean */}
{/* Dark Mode */}
```
### 🎨 60+ Pre-configured Themes
BigBlocks includes 60+ beautiful theme presets ready to use:
```tsx
import { BigBlocksThemeProvider, getThemePreset, themeCategories } from 'bigblocks';
// Use a pre-configured theme
// 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 →](./docs/STYLING_GUIDE.md)**
### Layout Constants
BigBlocks provides centralized layout constants for consistent sizing:
```tsx
import { CONTAINER_WIDTHS, SPACING, HEIGHTS } from 'bigblocks';
// Consistent card widths
// Responsive popovers
// Harmonious spacing
// Fixed header height
```
**[📐 Layout Constants Guide →](./docs/LAYOUT_CONSTANTS_GUIDE.md)**
## ⚠️ 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
```tsx
// ❌ WRONG
// ✅ CORRECT
```
See the [Integration Guide](./docs/INTEGRATION_GUIDE.md#common-implementation-mistakes) for more details.
## 📚 Documentation & Resources
### 🌐 **Complete Documentation**
**[bigblocks.dev](https://bigblocks.dev)** - Your one-stop resource for everything BigBlocks
### 📖 **Key Resources**
- **[📋 Quick Start Guide](https://bigblocks.dev/quickstart)** - Get up and running in minutes
- **[📚 Full Documentation](https://bigblocks.dev/docs)** - Comprehensive guides and API references
- **[🎨 Component Library](https://bigblocks.dev/components)** - Browse all available components with live examples
- **[🎨 Theme Gallery](https://bigblocks.dev/themes)** - Explore Bitcoin-inspired color themes
- **[🔌 MCP Server](https://bigblocks.dev/mcp-server)** - Model Context Protocol integration for AI assistants
### 🛠️ **Developer Tools**
- **[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Satchmo.bitcoin)** - Bitcoin development tools for VS Code
- **[GitHub Repository](https://github.com/bigblocks-dev/bigblocks)** - 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:
```bash
# 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](./tests/README.md) for more information about testing.
## 🔗 Links
- [GitHub Repository](https://github.com/b-open-io/bigblocks)
- [NPM Package](https://www.npmjs.com/package/bigblocks)
- [Quick Start Guide](./docs/getting-started/quick-start.md)
- [Component Examples](./examples/)
## 📜 License
MIT © [BigBlocks Team](https://github.com/bigblocks-dev)
---
**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](./examples/backend-setup-guide.md)** for complete instructions.
**Missing the `/api/auth/signin` endpoint will cause LoginForm to show "Loading..." forever.**
## Quick Start
### 1. Install
```bash
npm install bigblocks
```
### 2. Setup Backend (REQUIRED)
```typescript
// 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
```tsx
import { BitcoinAuthProvider, LoginForm } from 'bigblocks';
console.log('Logged in:', user)} />
```
### 4. Configure Blockchain Services (NEW!)
BigBlocks now supports flexible API key configuration for blockchain services:
```tsx
// Proxy Mode (Recommended - keeps API keys secure)
// Client Mode (for development/testing)
```
📖 **[API Key Configuration Guide](./docs/API_KEY_CONFIGURATION.md)** - Complete guide for configuring blockchain services
📖 **[Backend Setup Guide](./examples/backend-setup-guide.md)** - Full backend implementation details
---
## Components
// ... existing code ...