DOCSEARCHbyAlgolia
Submit Docs

Bitcoin Connect

repository·master·Indexed 41 days ago

https://github.com/getalby/bitcoin-connect

Web components and APIs to enable WebLN-based Lightning wallet connections and invoice payments directly within a website. It supports the WebLN and NWC protocols, allowing users to connect from desktop or mobile browsers without requiring browser extensions. Available as a core web components package (@getalby/bitcoin-connect v3.12.3) and a dedicated React package (@getalby/bitcoin-connect-react).

Tokens
13.9K
Snippets
55
Records
75
Agent score
100%

What's inside Bitcoin Connect

  1. Overview of Bitcoin Connect

    master

    Bitcoin Connect provides web components that enable websites to connect to Lightning wallets via the WebLN protocol. Unlike traditional wallet extensions, Bitcoin Connect is provided by the website itself, allowing users to connect from desktop or mobile browsers without installing an extension. It is compatible with pure HTML and all major JavaScript frameworks (React, Angular, Vue, Solid.js, etc.).

    Key features include:

    • Support for WebLN and NWC protocols.
    • An invoice payment UI that allows users to pay invoices with minimal code.
    • PWA compatibility.
    • Works across desktop and mobile devices.

  2. How Bitcoin Connect works

    master

    Bitcoin Connect acts as a bridge between your website and various Lightning wallet providers. It detects existing WebLN providers (like the Alby browser extension) and offers options to create new connections via protocols like NWC.

    Once a user selects a connector in the modal, a WebLN provider becomes available for your site to interact with the user's lightning wallet. The connection is persisted to localStorage so users remain connected across sessions.

    Key Benefits:

    • Works on mobile browsers and PWAs.
    • Works on desktop browsers even without a WebLN extension (via connectors).
    • Uses desktop extensions as the default if they are detected.

  3. Manage the WebLN global object

    master

    By default, webln is no longer injected into the window object. If your application requires it, you must manually assign it using onConnected and clean it up using onDisconnected to prevent stale connections after a user disconnects.

    import {onConnected, onDisconnected} from '@getalby/bitcoin-connect';

onConnected((provider) => {
  window.webln = provider;
});

onDisconnected(() => {
  delete window.webln;
});

  6. Integrate Bitcoin Connect in Next.js (SSR)

    master

    Because Bitcoin Connect relies on browser APIs, you must prevent it from rendering during Server-Side Rendering (SSR). In Next.js, use next/dynamic with ssr: false. If using the App Router, include the 'use client' directive at the top of your file.

    "use client"
import dynamic from 'next/dynamic';
const Button = dynamic(
  () => import('@getalby/bitcoin-connect-react').then((mod) => mod.Button),
  { 
    ssr: false 
  }
);

// Render the Button normally
<Button />

  7. Use Bitcoin Connect via HTML (CDN)

    master

    You can use Bitcoin Connect without any build tools by importing it directly from an ESM provider like esm.sh.

    To use the API (e.g., to launch the connection modal), import launchModal. To use the custom web components (like <bc-button>), import the package as a side-effect.

    <script type="module">
  import {launchModal} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2'; // jsdelivr.net, skypack.dev also work

  // use Bitcoin connect API normally...
  launchModal();

  // or if you just want access to the web components:
  // import 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2';
</script>

<!-- Bitcoin Connect components are now available -->
<bc-button></bc-button>

  8. Use Bitcoin Connect with React

    master

    The @getalby/bitcoin-connect-react package provides specialized components and hooks for React applications. You can use pre-built components like <Button />, <PayButton />, <Connect />, and <Payment /> to handle the entire user flow. For Next.js or SSR environments, ensure you only import and render these components on the client side using next/dynamic with ssr: false and the 'use client' directive.

    import {Button, PayButton, init, launchModal, launchPaymentModal, closeModal, requestProvider, Connect, SendPayment} from '@getalby/bitcoin-connect-react';

// Initialize Bitcoin Connect
init({
  appName: "My Lightning App",
})

// render the Bitcoin Connect button
<Button onConnect={(provider) => {
  const {preimage} = await provider.sendPayment("lnbc...");
}}/>

// render a "Pay Now" button
<PayButton invoice={invoice} onClick={() => {
  invoice = fetchInvoice();
  setInvoice(invoice)
}} onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>

// render the connect flow on its own without the modal
<Connect/>

// render the send payment flow on its own without the modal (for E-Commerce flows)
<Payment invoice="lnbc..." onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>

  9. Set up the Vite development environment

    master

    To develop Bitcoin Connect components using Vite, you must install dependencies in both the dev/vite directory and the project root directory. Once installed, you can start the development server using yarn dev from either location.

    # Install dependencies in both the dev/vite directory and the root
yarn install

# Start the development server
yarn dev

  12. Testing Bitcoin Connect with Lightning addresses

    master

    The Vite development examples use a test Lightning address. Because invoices in this environment cannot be paid with real sats, use the NWC faucet to obtain test sats for your development and testing workflows.

    Faucet URL: https://faucet.nwc.dev