⚡ Lightning Auth & Payment

The complete Lightning Network authentication and payment solution for modern web applications

Build Lightning Network-powered applications with ease. From simple single-page shops to complex eCommerce platforms, Lightning Auth & Payment provides everything you need for Lightning Network integration.

🚀 Quick Start

🚀 create-lightning-app (Fastest - 1 Command!)

For the fastest setup, use our new CLI that creates everything automatically:

# Create a complete Lightning app with one command
npx create-lightning-app my-lightning-app --typescript --tailwind

Done! 🎉 Your Lightning-enabled app is ready to run!

🚀 Alternative: Add to existing Next.js project

If you already have a Next.js project:

# 1. Install Lightning Auth & Payment
npm install lightning-auth-and-payment

# 2. Configure your project
npx lightning-auth-and-payment setup

Done! 🎉 Your Lightning-enabled app is running at http://localhost:3000

What the CLI does automatically:

• ✅ Installs Prisma and @prisma/client dependencies
• ✅ Creates .env file with secure configuration
• ✅ Generates Prisma schema for Lightning authentication
• ✅ Creates database library (src/lib/db.ts)
• ✅ Generates all API routes (/api/auth/lnurl, /api/auth/callback, etc.)
• ✅ Updates package.json with development scripts
• ✅ Sets up SQLite database with Prisma
• ✅ Configures HTTPS development server

CLI Options:

# Check current setup
npx lightning-setup check

# Setup with PostgreSQL
npx lightning-setup setup --database postgresql

# Force reconfigure
npx lightning-setup setup --force

🎨 UI Components & Storybook

The library includes a comprehensive set of Lightning-themed UI components with full Storybook documentation:

# View component library
npm run storybook

Available Components:

• LightningButton - Lightning-themed buttons with multiple variants
• LightningCard - Cards for payments, users, wallets, and more
• LightningBadge - Status badges with Lightning Network themes
• LightningInput - Enhanced input fields with Lightning styling
• LightningLogin - Complete login component with QR code
• LightningAuthModal - Authentication modal with wallet recommendations
• LightningPaymentModal - Payment processing modal
• ThemeToggle - Light/dark theme switcher

Features:

• 🎨 Lightning-themed design with orange gradients and Bitcoin aesthetics
• 🌙 Dark/Light mode support with system preference detection
• 📱 Responsive design that works on all screen sizes
• ♿ Accessibility with full ARIA support and keyboard navigation
• 🎭 Animation support with smooth transitions and hover effects
• 🎯 TypeScript with comprehensive type definitions
• 📚 Storybook documentation with live examples and usage guides

For AI Agents (Cursor, etc.)

Use our AI Setup Guide - copy and paste a single prompt to automatically configure everything.

📚 Examples Available

Check out our comprehensive examples in the /examples folder:

• 🚀 Next.js Full Example - Complete Lightning integration
• 🔐 Auth Only Example - Authentication without payments
• 💳 Payment Only Example - Payments without authentication
• ⚛️ React Example - React with Lightning integration
• 🚀 Express.js Example - Node.js API with Lightning

⚡ Zero-Config Setup (30 seconds!)

1. Install the library:

npm install lightning-auth-and-payment

2. Configure Next.js plugin in next.config.js:

Full Lightning Integration (Auth + Payments):

import { withLightning } from 'lightning-auth-and-payment/nextjs';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your existing config
};

// Zero-config: Auto-detects everything!
export default withLightning()(nextConfig);

Authentication Only:

import { withLightningAuth } from 'lightning-auth-and-payment/nextjs';

export default withLightningAuth()(nextConfig);

Payments Only:

import { withLightningPayment } from 'lightning-auth-and-payment/nextjs';

export default withLightningPayment()(nextConfig);

3. Start development:

npm run dev:lightning

That's it! The plugin automatically:

• 🔍 Detects your project configuration
• 🔧 Generates all API routes
• 📝 Creates environment files
• 🗄️ Sets up database schema
• 🔒 Configures HTTPS development
• 🚀 Adds development scripts

✨ Features

🔐 Lightning Authentication

• LNURL-auth Integration - Secure Lightning Network authentication
• Browser Extension Support - Works with Alby, Zeus, and other Lightning wallets
• Session Management - JWT-based secure sessions
• User Management - Complete user lifecycle management

💰 Lightning Payments

• BTCPay Server Integration - Full payment processing
• Invoice Management - Create, track, and manage Lightning invoices
• Payment Status Tracking - Real-time payment status updates
• Webhook Support - Secure payment notifications

🗄️ Database Support

• Prisma ORM - Type-safe database operations
• SQLite & PostgreSQL - Flexible database options
• Automatic Migrations - Database schema management
• Data Models - User, Session, Payment, and Order models

🔒 Security & Development

• HTTPS Development - SSL certificates for local development
• CORS Support - Proper cross-origin request handling
• Input Validation - Comprehensive data validation
• Error Handling - Secure error management

🎯 What You Get

Complete API Endpoints

• GET /api/auth/lnurl - LNURL authentication endpoint
• GET /api/auth/callback - Authentication callback handler
• GET /api/auth/status - Authentication status checker
• POST /api/auth/logout - User logout handler
• GET /api/user - User information endpoint

React Hooks & Components

• useLightningAuth() - Authentication state management
• useLightningPayment() - Payment processing
• LightningLogin - Ready-to-use login component
• PaymentModal - Payment interface component

Development Tools

• CLI Setup - npx lightning-setup setup
• Development Server - npx lightning-dev-server
• Database Management - Prisma integration
• TypeScript Support - Full type safety

💻 Usage Examples

Lightning Authentication

import { useLightningAuth } from 'lightning-auth-and-payment';

function LoginButton() {
  const { isAuthenticated, user, login, logout } = useLightningAuth();

  if (isAuthenticated) {
    return (
      <div>
        <p>Welcome, {user?.lnPubkey}</p>
        <button onClick={logout}>Logout</button>
      </div>
    );
  }

  return (
    <button onClick={login}>
      ⚡ Login with Lightning
    </button>
  );
}

Lightning Payments

import { useLightningPayment } from 'lightning-auth-and-payment';

function PaymentButton() {
  const { createInvoice, paymentStatus } = useLightningPayment();

  const handlePayment = async () => {
    const invoice = await createInvoice({
      amount: 1000, // 1000 sats
      description: 'My Lightning Payment'
    });
  };

  return (
    <button onClick={handlePayment}>
      💰 Pay with Lightning
    </button>
  );
}

API Routes

// src/app/api/user/route.ts
import { NextResponse } from 'next/server';
import { handleUserRequestWithAdapter, PrismaDatabaseAdapter } from 'lightning-auth-and-payment';
import { db } from '@/lib/db';

export async function GET() {
  const adapter = new PrismaDatabaseAdapter(db);
  const result = await handleUserRequestWithAdapter(adapter, sessionToken);
  return NextResponse.json(result);
}

🔧 Configuration

Environment Variables

# Required
DATABASE_URL="file:./dev.db"
SESSION_SECRET="your-super-secret-session-key-here"
NEXT_PUBLIC_APP_URL=https://localhost:3443

# BTCPay Server (optional)
BTCPAY_HOST=https://your-btcpay-server.com
BTCPAY_STORE_ID=your-store-id
BTCPAY_API_KEY=your-api-key
BTCPAY_WEBHOOK_SECRET=your-webhook-secret

Next.js Plugin Options

import { withLightning } from 'lightning-auth-and-payment/nextjs';

export default withLightning({
  database: 'prisma', // 'prisma' | 'memory'
  storage: 'database', // 'database' | 'memory'
  btcpay: true, // Enable BTCPay Server integration
  development: true, // Development mode
  authPrefix: '/api/auth',
  userPrefix: '/api/user',
  paymentPrefix: '/api/payment',
  webhookPrefix: '/api/webhooks'
})(nextConfig);

🚨 Troubleshooting

Common Issues

Port already in use:

lsof -ti:3000,3443 | xargs kill -9

Database connection issues:

npx prisma db push --force-reset

Missing dependencies:

rm -rf node_modules package-lock.json
npm install

Debug Mode

npx lightning-setup setup --verbose

Force Regeneration

npx lightning-setup setup --force

📚 Documentation

• 🔗 Quick Start Guide - Get started in 2 minutes
• 🛠️ Setup Guide - Complete setup documentation
• 📖 API Reference - Complete API documentation
• 🎯 Next.js Plugin - Plugin configuration
• 🚀 Examples - Working code examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/your-repo/lightning-auth-and-payment.git
cd lightning-auth-and-payment
npm install
npm run dev

📄 License

MIT License - see LICENSE for details.

🆘 Support

• 💬 Discord Community
• 🐛 GitHub Issues
• 📧 Email Support
• 📖 Documentation

🙏 Acknowledgments

• LNURL - Lightning Network URL specification
• BTCPay Server - Bitcoin payment processing
• Prisma - Database toolkit
• Next.js - React framework

Made with ⚡ for the Lightning Network community