Encrypted mesh-style messaging for the web. A Progressive Web App (PWA) that interoperates with the native BitChat iOS and Android apps through the Nostr protocol.
Live: bitbrowse.eth.limo
- Location Channels - Join conversations based on your geographic location using geohash
- Private DMs - End-to-end encrypted direct messages with NIP-17 gift wrapping
- Offline First - Full functionality after initial load, with background sync
- Cross-Platform - Messages visible to iOS and Android BitChat users
- Key Import - Bring your existing Nostr identity (nsec)
- P2P Sharing - Share the app via WiFi hotspot to others nearby
- Emergency Wipe - Triple-tap logo to instantly clear all data
- No Tracking - Zero analytics, completely private
- Decentralized Hosting - IPFS + ENS for censorship resistance
# Install dependencies
npm install
# Start development server
npm run dev
# Open http://localhost:5173| Command | Description |
|---|---|
npm run dev |
Start development server with HMR |
npm run build |
TypeScript check + production build |
npm run preview |
Preview production build locally |
npm run typecheck |
TypeScript type checking only |
npm run lint |
Run ESLint |
npm run lint:fix |
ESLint with auto-fix |
npm run format |
Format code with Prettier |
| Command | Description |
|---|---|
npm run test |
Run unit tests (Vitest) |
npm run test:watch |
Run tests in watch mode |
npm run test:coverage |
Run tests with coverage report |
npm run test:e2e |
Run E2E tests (Playwright) |
npm run test:e2e:headed |
Run E2E tests with browser UI |
npm run test:e2e:debug |
Debug E2E tests |
npm run test:all |
Run both unit and E2E tests |
| Command | Description |
|---|---|
npm run test:security |
Run security test suite |
npm run security:scan |
Run security vulnerability scan |
npm run security:audit |
Full security audit |
| Command | Description |
|---|---|
npm run test:bench |
Run benchmark tests |
npm run analyze:bundle |
Analyze bundle size |
npm run perf:all |
Run all performance checks |
| Layer | Technology |
|---|---|
| Framework | Preact + TypeScript |
| Build | Vite 5.x |
| Styling | Tailwind CSS (terminal aesthetic) |
| State | Zustand (persisted) |
| Storage | OPFS + IndexedDB fallback |
| Crypto | libsodium.js (XChaCha20-Poly1305, Ed25519, X25519) |
| Messaging | nostr-tools + Trystero (WebRTC) |
| Offline | Workbox Service Worker |
| Testing | Vitest + Playwright |
src/
├── components/ # Preact UI components
│ ├── chat/ # Chat interface (MessageList, MessageInput)
│ ├── channels/ # Channel management
│ ├── layout/ # Shell, Header, Navigation
│ ├── onboarding/ # Setup wizard
│ ├── peers/ # Peer management
│ ├── settings/ # Settings views
│ └── sharing/ # P2P app sharing
├── services/ # Core business logic
│ ├── crypto/ # libsodium encryption, signing, hashing
│ ├── nostr/ # Nostr client, relays, events, NIP-17
│ ├── storage/ # OPFS/IndexedDB storage abstraction
│ └── webrtc/ # Trystero P2P connections
├── stores/ # Zustand state management
│ ├── identity-store.ts # User identity (public key, fingerprint)
│ ├── messages-store.ts # Chat messages by channel
│ ├── channels-store.ts # Channel list and state
│ ├── peers-store.ts # Known peers
│ └── settings-store.ts # User preferences
├── workers/ # Service Worker (sw.ts)
└── types/ # TypeScript type definitions
BitChat In Browser is deployed to IPFS and served via ENS for decentralized, censorship-resistant hosting.
# Build the project
npm run build
# Deploy (requires PINATA_JWT env var)
npm run deploy:ipfs
# Output: CID like bafybeig...After deployment, update the ENS content hash for bitbrowse.eth:
- Go to app.ens.domains
- Connect the wallet that owns
bitbrowse.eth - Navigate to
bitbrowse.eth> Records - Set Content Hash to:
ipfs://<CID>(CID from deployment output) - Confirm transaction
- Verify at bitbrowse.eth.limo
For IPFS deployment, set in GitHub Secrets or .env:
PINATA_JWT=your_pinata_jwt_token
WEB3_STORAGE_TOKEN=your_web3_storage_token # optional backupAfter deployment, the app is accessible via:
https://bitbrowse.eth.limo(primary, after ENS update)https://<CID>.ipfs.dweb.linkhttps://gateway.pinata.cloud/ipfs/<CID>
For full mesh networking capabilities including Bluetooth:
| Feature | Web | iOS | Android |
|---|---|---|---|
| Location Channels | Yes | Yes | Yes |
| Private DMs (NIP-17) | Yes | Yes | Yes |
| Offline Storage | Yes | Yes | Yes |
| Offline Queue | Yes | Yes | Yes |
| Emergency Wipe | Yes | Yes | Yes |
| IRC Commands | Yes | Yes | Yes |
| @Mentions | Yes | Yes | Yes |
| BLE Mesh | No | Yes | Yes |
| Background BLE | No | Yes | Yes |
| Key Import | Yes | No | No |
| P2P App Sharing | Yes | No | No |
| Feature | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|
| Core messaging | Yes | Yes | Yes | Yes |
| Service Worker | Yes | Yes | Yes | Yes |
| Add to Home Screen | Yes | Yes | Yes | Yes |
| Push Notifications | Yes | Yes | Limited | Yes |
| OPFS Storage | Yes | Yes | Yes | Yes |
Note: Bluetooth mesh networking is not available in browsers. Use native apps for BLE mesh.
- Architecture - System design and component overview
- Development - Setup, coding standards, debugging
- Protocol - Nostr protocol usage and NIP implementations
- Privacy - Data handling and privacy guarantees
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
npm run test:all) - Run linting (
npm run lint) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Offline First: All features must work offline after initial load
- Bundle Size: Keep initial bundle under 500KB
- Compatibility: Match BitChat native behavior exactly
- No Analytics: Zero tracking, completely private
- Terminal Aesthetic: Match iOS/Android app visual style
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
See UNLICENSE for details.
- Web App: bitbrowse.eth.limo
- iOS App: App Store
- Android App: Play Store
- GitHub: permissionlesstech/bitchat-in-browser