Skip to content

README.md

Latest commit

 

History

History
124 lines (94 loc) · 7.9 KB

README.md

File metadata and controls

124 lines (94 loc) · 7.9 KB
Raw

LightningConnect

Live demo: lightningconnect.lovable.app

Zero-friction Bitcoin wallet connection for any web app.

LightningConnect is a drop-in React widget + hook that solves wallet connection and automatic payment detection for Bitcoin web apps. Blink-native, universally compatible, and built so developers never write polling logic again.

  • Blink-native — two dedicated Blink connectors (Address + API Key)
  • Universally compatible — generic Lightning Address + NWC for every other wallet
  • Auto payment detection — onPayment callback fires once, automatically
  • Auto cleanup — watchers stop on PAID/EXPIRED and on unmount
  • Light & dark mode — built-in theme toggle with persisted preference
  • Encrypted local storage — device-bound via Web Crypto
  • <30kb gzipped — only React as a peer dep
npm install lightningconnect

Quick start

import { LightningConnect, useWalletConnect } from "lightningconnect";

export default function App() {
  const { connect, isConnected, makeInvoice } = useWalletConnect({
    onPayment: (invoice) => alert(`Paid: ${invoice.amount} sats`),
    onExpiry: (invoice) => console.log("Expired", invoice.paymentHash),
  });

  return (
    <>
      <LightningConnect theme={{ primary: "#F7931A" }} />
      {isConnected ? (
        <button onClick={() => makeInvoice(1000, "BTC", "Coffee")}>
          Get paid 1000 sats
        </button>
      ) : (
        <button onClick={connect}>Connect wallet</button>
      )}
    </>
  );
}

No setInterval, no useEffect, no cleanup. LightningConnect starts watching as soon as makeInvoice() resolves and fires onPayment exactly once when it settles.

The four connectors

LightningConnect groups its connectors into two categories — Blink (native, premium) and Other Wallets (universal compatibility).

Category Connector Best for
Blink Blink Lightning Address Most users. Just a username, no setup.
Blink Blink API Key Power users. Full account control.
Other ₿ Lightning Address Any user@domain — WoS, Alby, Strike, etc.
Other Nostr Wallet Connect (Beta) Alby Hub, Zeus, Phoenix, Mutiny

This repo

This repository contains two things:

  1. /lightningconnect/ — the npm package (source, tests, build config)
  2. /src/ — the marketing site and live playground at lightningconnect.lovable.app

Package structure

lightningconnect/
├── src/
│   ├── widget.tsx              # <LightningConnect /> modal component
│   ├── hooks/
│   │   └── useWalletConnect.ts # Core hook with payment detection
│   ├── connectors/             # Blink Address, Blink API, LNURL, NWC
│   ├── lib/
│   │   └── paymentWatcher.ts   # Standalone watchPayment utility
│   └── index.ts                # Public exports
├── README.md                   # Full package docs
├── package.json
└── ...

Site structure

src/
├── routes/
│   ├── index.tsx               # Landing page + live playground
│   └── readme.tsx              # Inline README viewer
├── router.tsx
└── ...

Running locally

# Install dependencies
bun install

# Run tests
bun test

# Start dev server (site + playground)
bun run dev

# Build package
bun run build:lib

Documentation

Full API documentation lives in lightningconnect/README.md and covers:

  • useWalletConnect hook API and callbacks
  • watchPayment standalone utility
  • Connector details and setup instructions
  • Theming (dark mode, light mode, custom overrides)
  • Encrypted storage and export/import
  • TypeScript types

License

MIT.