LunoKit

Connectwallet modal

Inspiration

Building DApps in the Polkadot ecosystem, we repeatedly faced the same frustrating challenge: every project required rebuilding wallet connection infrastructure from scratch.

We watched Ethereum developers effortlessly use wagmi + RainbowKit while we spent days wrestling with:

Inconsistent wallet APIs across Polkadot.js, SubWallet, Talisman, and others
Complex state management for accounts, chains, and connections
Repetitive UI implementation for wallet selection and account displays

Polkadot deserved better. The ecosystem needed a unified, developer-friendly solution that could match Ethereum's tooling quality. So we built LunoKit - the complete wallet connection infrastructure that Polkadot has been missing.

What it does

LunoKit is wagmi + RainbowKit for Polkadot - a comprehensive wallet connection library that lets developers integrate wallet functionality in minutes, not days.

Core Features

🔄 Compatible with Existing Projects

Seamlessly works alongside Dedot, PAPI, and @polkadot/api
Flexible integration: use just for wallet connections or leverage the full API

🔌 9 Wallet Integrations

Polkadot{.js}, SubWallet, Talisman, Nova Wallet, PolkaGate, WalletConnect, Enkrypt, Fearless, Mimir
Unified connector API hides wallet-specific quirks
Automatic wallet detection and availability checking

⚡ 25+ React Hooks

Connection: useConnect, useDisconnect, useStatus, useConnectors, useActiveConnector
Account: useAccount, useAccounts, useBalance
Chain: useChain, useChains, useSwitchChain
Transaction: useSendTransaction, useSignMessage, useSigner, usePapiSigner, useEstimatePaymentInfo
Data: useBlockNumber, useSubscription, useRuntimeVersion, useGenesisHash
API: useApi, useConfig

🎨 Beautiful Pre-built UI Components

ConnectButton, ConnectModal, AccountDetailsModal
Responsive design that works perfectly on mobile and desktop
Customizable themes with CSS variables
Accessible (a11y compliant) out of the box

🌐 Extensive Chain Support

Polkadot + Asset Hub, Coretime, Collectives, People
Kusama + Asset Hub, People, Coretime
Westend + Asset Hub (testnet)
Paseo + Asset Hub, Passet Hub (community testnet)
Any custom Substrate chain with simple configuration

📱 Mobile-First Design

Deeplink support for SubWallet and other mobile wallets
Device detection and automatic flow optimization
QR code scanning for WalletConnect

How we built it

Modular Architecture

LunoKit is built with three independent layers that work together seamlessly:

@luno-kit/core - Foundation layer

Wallet connector abstractions (BaseConnector)
Chain configuration system
Account management logic
Storage and session handling
Signer interfaces for multiple API libraries

@luno-kit/react - Integration layer

25+ composable React Hooks
Zustand-powered state management
TanStack Query for data caching and subscriptions
Session persistence and recovery
TypeScript-first with comprehensive types

@luno-kit/ui - Presentation layer

10+ pre-built React components
Tailwind CSS + Radix UI foundation
CSS variable-based theming
Responsive and accessible design

Technology Stack

Zustand for State Management: Lightweight, performant, and perfect for our use case without the complexity of Redux.

TanStack Query for Data: Battle-tested solution for async state management, caching, and automatic refetching.

Monorepo with pnpm: Clean package separation with shared tooling, Changesets for versioning, and automated NPM publishing.

Key Design Decisions

Multi-API Compatibility: Support for Dedot, PAPI, and @polkadot/api through flexible signer interfaces (useSigner and usePapiSigner).

Flexible Integration Modes:

Full API mode: Complete solution with chain management and transactions
Wallet-only mode: Just connection features, use your own API library
Custom UI mode: Use hooks without our UI components

Mobile-First Approach: Built-in deeplink support, device detection, and responsive UI from day one.

Type Safety First: Comprehensive TypeScript types prevent runtime errors and provide excellent developer experience.

Accomplishments that we're proud of

✅ Production-Ready Product

Live demo at demo.lunolab.xyz
Complete documentation at docs.lunolab.xyz
Published on NPM and ready for immediate use

✅ Comprehensive Feature Set

25+ React Hooks covering every wallet interaction use case
9 wallet integrations with unified API
10+ pre-built UI components
Support for Polkadot, Kusama, and all parachains

✅ Multi-Framework Examples

Vite (fastest development experience)
Next.js App Router (latest Next.js pattern)
Next.js Pages Router (traditional Next.js)
Create React App (classic React setup)

✅ Developer Experience

10-minute quick start guide
Comprehensive API reference
Clear, example-rich documentation
TypeScript-first with full type safety

✅ Flexible Architecture

Use only what you need (core/react/ui)
Compatible with existing API libraries
Custom wallet and chain support
Theme customization system

What we learned

Abstraction vs. Flexibility balance: A good library needs to hide complexity while still allowing customization. Our three-layer architecture (core/react/ui) lets developers use as much or as little as they need.

Type safety prevents runtime errors: Comprehensive TypeScript types catch issues at compile time, saving debugging hours and improving developer confidence.

Mobile requires dedicated solutions: Mobile wallet connections require fundamentally different flows (deeplinks, QR codes, mobile-optimized UI), not just responsive design.

Documentation matters as much as code: Clear examples and a working demo convert more users than technical specs. We invested heavily in both.

Polkadot needs standardization: The ecosystem lacks standardized wallet connection tooling like Ethereum has with wagmi. Developers are rebuilding the same logic repeatedly.

Multi-API support is essential: Different teams prefer different libraries (Dedot vs PAPI vs Polkadot.js). Supporting all of them makes LunoKit universally accessible.

Show, don't tell: Our live demo at demo.lunolab.xyz demonstrates capabilities better than any documentation.