@bitcoin-os/bapps

Create new Bitcoin apps with Next.js and full Bitcoin OS integration.

Installation

npm install -g @bitcoin-os/bapps

Usage

Quick Start

# Create a new Bitcoin app
npx @bitcoin-os/bapps my-bitcoin-app

# Or use the global command
create-bapp my-bitcoin-app

Interactive Setup

create-bapp

The CLI will guide you through:

• App name and display name
• Template selection
• Color scheme
• Feature selection (auth, blockchain, payments)

Templates Available

• Basic Bitcoin App - Simple starter template
• Document Editor - Like Bitcoin Writer with rich text editing
• File Storage - Like Bitcoin Drive with file management
• Email Client - Like Bitcoin Email with messaging
• Media Player - Like Bitcoin Music with media playback
• Calendar App - Like Bitcoin Calendar with scheduling
• Trading Platform - Like Bitcoin Exchange with market data
• Wallet Interface - Like Bitcoin Wallet with transaction management
• Custom App - Minimal setup for custom implementations

Command Line Options

create-bapp my-app --template basic --yes

Options:

• -t, --template <template> - Choose template without prompt
• -y, --yes - Skip prompts and use defaults
• -h, --help - Show help

What You Get

Every Bitcoin app created includes:

🎨 Full Bitcoin OS Integration

• TopMenuBar - macOS-style menu with Bitcoin apps dropdown
• Dock - Bottom dock with Bitcoin apps and system status
• DevSidebar - Left sidebar with navigation and stats
• ProofOfConceptBar - Top banner for development

⚡ Modern Stack

• Next.js 14 with App Router
• TypeScript for type safety
• Tailwind CSS for styling
• ESLint for code quality

🔧 Optional Integrations

• HandCash Connect - For user authentication
• Bitcoin SV - For blockchain operations
• Payment Processing - For monetization

📁 Generated Structure

my-bitcoin-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx     # Bitcoin OS provider setup
│   │   ├── page.tsx       # Main app component
│   │   └── globals.css    # Global styles
├── public/                # Static assets
├── .env.local.example     # Environment template
├── package.json           # Dependencies and scripts
└── README.md             # App documentation

Example Usage

Create a Document Editor

create-bapp bitcoin-docs --template writer
cd bitcoin-docs
npm run dev

Create a Trading Platform

create-bapp bitcoin-trader --template exchange
cd bitcoin-trader
npm run dev

Custom Configuration

create-bapp my-app
# Interactive prompts for:
# - Display name: "My Bitcoin App"
# - Template: Custom App
# - Color: Orange (#f97316)
# - Auth: Yes
# - Blockchain: Yes
# - Payments: No

Features Included

Bitcoin OS Components

All apps get the full Bitcoin OS experience:

import { BitcoinOSProvider } from '@bitcoin-os/bridge'

const config = {
  context: {
    appName: 'My Bitcoin App',
    exchangeUrl: 'https://my-app-exchange.vercel.app',
    branding: {
      name: 'My Bitcoin App',
      color: '#f97316'
    }
  },
  showDevSidebar: true,
  showDock: true,
  showPocBar: true
}

<BitcoinOSProvider config={config}>
  {children}
</BitcoinOSProvider>

HandCash Authentication

import { HandCashConnect } from '@handcash/handcash-connect'

const handcashConnect = new HandCashConnect({
  appId: process.env.NEXT_PUBLIC_HANDCASH_APP_ID,
  appSecret: process.env.NEXT_PUBLIC_HANDCASH_APP_SECRET
})

const authToken = await handcashConnect.requestPermissions()
const account = handcashConnect.getAccountFromAuthToken(authToken)
const profile = await account.profile.getCurrentProfile()

Blockchain Integration

import { Bsv } from 'bsv'

// Bitcoin SV operations
const privateKey = Bsv.PrivateKey.fromRandom()
const publicKey = privateKey.toPublicKey()
const address = publicKey.toAddress()

Deployment

All generated apps are ready for deployment:

Vercel (Recommended)

npx vercel

Netlify

npm run build
# Deploy the 'out' folder

Self-hosted

npm run build
npm start

Environment Variables

Generated apps include environment templates:

# .env.local
NEXT_PUBLIC_HANDCASH_APP_ID=your-app-id
NEXT_PUBLIC_HANDCASH_APP_SECRET=your-app-secret

Get credentials from HandCash Dashboard.

Development

Local Development

git clone https://github.com/bitcoin-corp/bitcoin-OS.git
cd bitcoin-OS/packages/bapps
npm install
npm link

Testing

# Test app creation
create-bapp test-app --template basic --yes
cd test-app
npm run dev

Examples

Minimal App

create-bapp minimal --template custom --yes

Generates a basic Bitcoin app with just the OS integration.

Full-Featured App

create-bapp feature-rich --template writer
# Select: Auth=Yes, Blockchain=Yes, Payments=Yes

Generates an app with all integrations enabled.

Contributing

This package is part of the Bitcoin OS project. See the main repository for contribution guidelines.

License

Open-BSV-4.0 © The Bitcoin Corporation Ltd

Ready to build Bitcoin apps?

npx @bitcoin-os/bapps my-awesome-app

Visit bitcoin-os.vercel.app for more information.