@connector-kit/connector
Advanced tools
Headless wallet connector client and React provider built on Wallet Standard
Headless wallet connector built on Wallet Standard with powerful transaction signing, event system, and performance optimizations.
Enhanced with production-ready features:
pnpm add @connector-kit/connector
import { ConnectorProvider, getDefaultConfig } from '@connector-kit/connector';
function App() {
return (
<ConnectorProvider config={getDefaultConfig({ appName: "My App" })}>
<YourApp />
</ConnectorProvider>
);
}
import { useConnector, useAccount } from '@connector-kit/connector';
function WalletButton() {
const { wallets, select, disconnect, connected } = useConnector();
const { address, formatted, copy } = useAccount();
if (!connected) {
return (
<div>
{wallets.map(w => (
<button key={w.name} onClick={() => select(w.name)}>
Connect {w.name}
</button>
))}
</div>
);
}
return (
<div>
<button onClick={copy}>{formatted}</button>
<button onClick={disconnect}>Disconnect</button>
</div>
);
}
import { useTransactionSigner } from '@connector-kit/connector';
function SendTransaction() {
const { signer, ready, capabilities } = useTransactionSigner();
const handleSend = async () => {
if (!signer) return;
const signature = await signer.signAndSendTransaction(transaction);
console.log('Transaction sent:', signature);
};
return (
<button onClick={handleSend} disabled={!ready}>
Send Transaction
</button>
);
}
That's it! You're ready to build. Everything else below is optional.
useConnector()Main hook for wallet connection and state.
import { useConnector } from '@connector-kit/connector';
function Component() {
const {
// State
wallets, // WalletInfo[] - All available wallets
selectedWallet, // Wallet | null - Currently connected wallet
accounts, // AccountInfo[] - Connected accounts
connected, // boolean - Connection status
connecting, // boolean - Connecting in progress
// Actions
select, // (walletName: string) => Promise<void>
disconnect, // () => Promise<void>
} = useConnector();
}
useAccount()Hook for working with the connected account.
import { useAccount } from '@connector-kit/connector';
function Component() {
const {
address, // string | null - Full wallet address
formatted, // string - Shortened address (e.g., "5Gv8...x3kF")
copy, // () => Promise<boolean> - Copy address to clipboard
copied, // boolean - True for 2s after copying
connected, // boolean - Connection status
accounts, // AccountInfo[] - All accounts
selectAccount // (address: string) => Promise<void>
} = useAccount();
}
useCluster()Hook for managing Solana network/cluster.
import { useCluster } from '@connector-kit/connector';
function Component() {
const {
cluster, // SolanaCluster | null - Active cluster
clusters, // SolanaCluster[] - Available clusters
setCluster, // (id: SolanaClusterId) => Promise<void>
isMainnet, // boolean - Convenience flags
isDevnet, // boolean
rpcUrl, // string - RPC endpoint URL
explorerUrl // string - Solana Explorer base URL
} = useCluster();
}
Clean, unified interface for transaction signing operations.
import { useTransactionSigner } from '@connector-kit/connector';
function SendTx() {
const { signer, ready, capabilities } = useTransactionSigner();
// Check capabilities
console.log('Can sign:', capabilities.canSign);
console.log('Can send:', capabilities.canSend);
console.log('Can sign messages:', capabilities.canSignMessage);
console.log('Batch support:', capabilities.supportsBatchSigning);
const handleSend = async () => {
if (!signer) return;
try {
// Sign and send a transaction
const signature = await signer.signAndSendTransaction(transaction);
console.log('Success:', signature);
// Or just sign without sending
const signed = await signer.signTransaction(transaction);
// Or sign multiple transactions
const signedBatch = await signer.signAllTransactions([tx1, tx2, tx3]);
// Or sign and send multiple
const signatures = await signer.signAndSendTransactions([tx1, tx2]);
} catch (error) {
if (error instanceof TransactionSignerError) {
console.error('Signing error:', error.code, error.message);
}
}
};
return (
<button onClick={handleSend} disabled={!ready}>
Send Transaction
</button>
);
}
Error Handling:
import { isTransactionSignerError, TransactionSignerError } from '@connector-kit/connector';
try {
await signer.signAndSendTransaction(tx);
} catch (error) {
if (isTransactionSignerError(error)) {
switch (error.code) {
case 'WALLET_NOT_CONNECTED':
// Show connect prompt
break;
case 'FEATURE_NOT_SUPPORTED':
// Show unsupported feature message
break;
case 'SIGNING_FAILED':
// User rejected or signing failed
break;
case 'SEND_FAILED':
// Transaction broadcast failed
break;
}
}
}
Track all connector lifecycle events for analytics and monitoring.
import { useConnectorClient } from '@connector-kit/connector';
function AnalyticsTracker() {
const client = useConnectorClient();
useEffect(() => {
if (!client) return;
// Subscribe to events
const unsubscribe = client.on((event) => {
switch (event.type) {
case 'wallet:connected':
analytics.track('Wallet Connected', {
wallet: event.wallet,
account: event.account,
timestamp: event.timestamp
});
break;
case 'wallet:disconnected':
analytics.track('Wallet Disconnected');
break;
case 'cluster:changed':
analytics.track('Network Changed', {
from: event.previousCluster,
to: event.cluster
});
break;
case 'error':
errorTracker.captureException(event.error, {
context: event.context
});
break;
}
});
return unsubscribe;
}, [client]);
return null;
}
Available Events:
wallet:connected - Wallet successfully connectedwallet:disconnected - Wallet disconnectedwallet:changed - Selected wallet changedaccount:changed - Selected account changedcluster:changed - Network/cluster changedwallets:detected - New wallets detectedconnecting - Connection attempt startedconnection:failed - Connection attempt failederror - Error occurredFloating development panel for instant state visibility.
import { ConnectorDebugPanel } from '@connector-kit/connector';
function App() {
return (
<ConnectorProvider config={config}>
{/* Only visible in development mode */}
{process.env.NODE_ENV === 'development' && <ConnectorDebugPanel />}
<YourApp />
</ConnectorProvider>
);
}
Features:
Custom positioning:
<ConnectorDebugPanel
position="top-left" // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
defaultOpen={true}
zIndex={10000}
/>
Reusable RPC connections for better performance.
import { ConnectionPool, createConnectionPool } from '@connector-kit/connector/headless';
import { Connection } from '@solana/web3.js';
// Create custom pool
const pool = createConnectionPool({
maxSize: 10,
createConnection: (cluster) => {
return new Connection(cluster.endpoint, {
commitment: 'confirmed'
});
}
});
// Get or create connection for a cluster
const connection = pool.get(currentCluster);
const balance = await connection.getBalance(publicKey);
// Clear specific connection when settings change
pool.clear('solana:mainnet');
// Get pool statistics
const stats = pool.getStats();
console.log(`Pool: ${stats.size}/${stats.maxSize}`);
console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses) * 100}%`);
Global pool (simpler):
import { getConnectionPool } from '@connector-kit/connector/headless';
const pool = getConnectionPool();
const connection = pool.get(cluster);
Comprehensive diagnostics for debugging and monitoring.
import { useConnectorClient } from '@connector-kit/connector';
function HealthMonitor() {
const client = useConnectorClient();
if (!client) return null;
const health = client.getHealth();
return (
<div>
<h3>Connector Health</h3>
<div>Initialized: {health.initialized ? '✓' : '✗'}</div>
<div>Wallet Standard: {health.walletStandardAvailable ? '✓' : '✗'}</div>
<div>Storage: {health.storageAvailable ? '✓' : '✗'}</div>
<div>Wallets Detected: {health.walletsDetected}</div>
{health.errors.length > 0 && (
<div className="errors">
{health.errors.map(err => <div key={err}>{err}</div>)}
</div>
)}
</div>
);
}
Drop-in replacement for libraries expecting @solana/wallet-adapter.
import { useTransactionSigner, useConnector } from '@connector-kit/connector';
import { createWalletAdapterCompat } from '@connector-kit/connector/compat';
function JupiterIntegration() {
const { signer } = useTransactionSigner();
const { disconnect } = useConnector();
// Create wallet-adapter compatible interface
const walletAdapter = createWalletAdapterCompat(signer, {
disconnect: async () => {
await disconnect();
},
onError: (error, operation) => {
console.error(`Wallet adapter error in ${operation}:`, error);
}
});
// Use with Jupiter, Serum, or any wallet-adapter library
return <JupiterTerminal wallet={walletAdapter} />;
}
Compatible with:
import { getDefaultConfig } from '@connector-kit/connector';
const config = getDefaultConfig({
appName: 'My App', // Required
autoConnect: true, // Auto-reconnect (default: true)
network: 'mainnet-beta', // Initial network
enableMobile: true, // Mobile Wallet Adapter (default: true)
debug: false, // Debug logging
// NEW: Custom error handler
onError: (error, errorInfo) => {
console.error('Connector error:', error);
errorTracker.captureException(error, errorInfo);
}
});
const config = getDefaultConfig({
appName: 'My App',
network: 'devnet' // 'mainnet-beta' | 'devnet' | 'testnet' | 'localnet'
});
import { getDefaultConfig, createSolanaMainnet } from '@connector-kit/connector';
const config = getDefaultConfig({
appName: 'My App',
clusters: [
createSolanaMainnet({
endpoint: 'https://my-custom-rpc.com'
})
],
customClusters: [
// Add additional custom clusters
]
});
<ConnectorProvider
config={config}
mobile={{
appIdentity: {
name: 'My App',
uri: 'https://myapp.com',
icon: 'https://myapp.com/icon.png'
}
}}
>
<App />
</ConnectorProvider>
Use ConnectorClient for non-React frameworks.
import { ConnectorClient, getDefaultConfig } from '@connector-kit/connector/headless';
// Create client
const client = new ConnectorClient(
getDefaultConfig({ appName: 'My App' })
);
// Get state
const state = client.getSnapshot();
console.log('Wallets:', state.wallets);
// Connect
await client.select('Phantom');
// Subscribe to changes
const unsubscribe = client.subscribe((state) => {
console.log('State updated:', state);
});
// Subscribe to events (NEW!)
const unsubEvents = client.on((event) => {
console.log('Event:', event.type, event);
});
// Check health (NEW!)
const health = client.getHealth();
console.log('Health:', health);
// Disconnect
await client.disconnect();
// Cleanup
client.destroy();
If you're using both ConnectorKit and Armadura:
import { createConfig, AppProvider } from '@connector-kit/connector';
import { ArmaProvider } from '@armadura/sdk';
const config = createConfig({
appName: 'My App',
network: 'mainnet',
rpcUrl: 'https://my-custom-rpc.com',
autoConnect: true
});
function App() {
return (
<AppProvider config={config.connectorConfig}>
<ArmaProvider
config={{
network: config.network,
rpcUrl: config.rpcUrl,
providers: [/* ... */]
}}
useConnector="auto"
>
{children}
</ArmaProvider>
</AppProvider>
);
}
Most users don't need to configure storage - it works automatically with validation, error handling, and SSR fallback.
Only customize for:
import {
getDefaultConfig,
createEnhancedStorageWallet,
EnhancedStorageAdapter
} from '@connector-kit/connector';
const config = getDefaultConfig({
appName: 'My App',
storage: {
wallet: new EnhancedStorageAdapter(
createEnhancedStorageWallet({
validator: (walletName) => {
// Custom validation
return walletName !== null && walletName.length > 0;
},
onError: (error) => {
Sentry.captureException(error);
}
})
),
// account and cluster use defaults if not specified
}
});
// Full library - includes React and headless
import { ConnectorProvider, useConnector } from '@connector-kit/connector';
// Headless core only - no React
import { ConnectorClient, getDefaultConfig } from '@connector-kit/connector/headless';
// React-specific exports only
import { useConnector, useAccount } from '@connector-kit/connector/react';
// Wallet adapter compatibility bridge
import { createWalletAdapterCompat } from '@connector-kit/connector/compat';
getDefaultConfig(options)const config = getDefaultConfig({
appName: string, // Required: App name
appUrl?: string, // App URL for metadata
autoConnect?: boolean, // Auto-reconnect (default: true)
debug?: boolean, // Debug logging
network?: 'mainnet' | 'mainnet-beta' // Initial network (default: mainnet-beta)
| 'devnet' | 'testnet' | 'localnet',
enableMobile?: boolean, // Mobile Wallet Adapter (default: true)
storage?: ConnectorConfig['storage'], // Custom storage adapters
clusters?: SolanaCluster[], // Override default clusters
customClusters?: SolanaCluster[], // Add custom clusters
persistClusterSelection?: boolean, // Persist cluster (default: true)
enableErrorBoundary?: boolean, // Error boundaries (default: true)
maxRetries?: number, // Retry attempts (default: 3)
onError?: (error, errorInfo) => void // Error handler (NEW!)
});
useTransactionSigner()React hook for transaction operations.
interface UseTransactionSignerReturn {
signer: TransactionSigner | null; // Signer instance
ready: boolean; // Whether signer is ready
address: string | null; // Current address
capabilities: TransactionSignerCapabilities; // What signer can do
}
createTransactionSigner(config)Create a transaction signer (headless).
import { createTransactionSigner } from '@connector-kit/connector/headless';
const signer = createTransactionSigner({
wallet: connectedWallet,
account: selectedAccount,
cluster: currentCluster // Optional
});
TransactionSigner Interfaceinterface TransactionSigner {
readonly address: string;
signTransaction(tx: any): Promise<any>;
signAllTransactions(txs: any[]): Promise<any[]>;
signAndSendTransaction(tx: any, options?: SendOptions): Promise<string>;
signAndSendTransactions(txs: any[], options?: SendOptions): Promise<string[]>;
signMessage?(message: Uint8Array): Promise<Uint8Array>;
getCapabilities(): TransactionSignerCapabilities;
}
type ConnectorEvent =
| { type: 'wallet:connected'; wallet: string; account: string; timestamp: string }
| { type: 'wallet:disconnected'; timestamp: string }
| { type: 'cluster:changed'; cluster: string; previousCluster: string | null; timestamp: string }
| { type: 'wallets:detected'; count: number; timestamp: string }
| { type: 'connecting'; wallet: string; timestamp: string }
| { type: 'connection:failed'; wallet: string; error: string; timestamp: string }
| { type: 'error'; error: Error; context: string; timestamp: string }
// Subscribe to events
const unsubscribe = client.on((event) => {
console.log('Event:', event.type, event);
});
// Unsubscribe
client.off(listener);
// Unsubscribe all
client.offAll();
interface ConnectorHealth {
initialized: boolean;
walletStandardAvailable: boolean;
storageAvailable: boolean;
walletsDetected: number;
errors: string[];
connectionState: {
connected: boolean;
connecting: boolean;
hasSelectedWallet: boolean;
hasSelectedAccount: boolean;
};
timestamp: string;
}
// Get health status
const health = client.getHealth();
class ConnectionPool {
get(cluster: SolanaCluster): ConnectionLike;
has(clusterId: string): boolean;
clear(clusterId: string): void;
clearAll(): void;
getStats(): ConnectionPoolStats;
resetStats(): void;
}
// Create pool
const pool = createConnectionPool(options);
// Get global pool
const pool = getConnectionPool();
// Create wallet-adapter compatible interface
createWalletAdapterCompat(
signer: TransactionSigner | null,
options: {
disconnect: () => Promise<void>;
transformTransaction?: (tx: any) => any;
onError?: (error: Error, operation: string) => void;
}
): WalletAdapterCompatible
// React hook version
useWalletAdapterCompat(
signer: TransactionSigner | null,
disconnect: () => Promise<void>,
options?: Omit<WalletAdapterCompatOptions, 'disconnect'>
): WalletAdapterCompatible
// Type guard
isWalletAdapterCompatible(obj: any): obj is WalletAdapterCompatible
import {
installPolyfills,
isPolyfillInstalled,
isCryptoAvailable,
getPolyfillStatus
} from '@connector-kit/connector/headless';
// Install browser polyfills (automatic in React provider)
installPolyfills();
// Check status
const installed = isPolyfillInstalled();
const cryptoAvailable = isCryptoAvailable();
const status = getPolyfillStatus();
import { formatSOL, formatAddress } from '@connector-kit/connector';
// Format SOL amounts
formatSOL(1500000000, { decimals: 4 }) // "1.5000 SOL"
// Format addresses
formatAddress(address, { length: 6 }) // "5Gv8yU...8x3kF"
// Lightweight versions (smaller bundle, no Intl)
import { formatSOLSimple, formatAddressSimple } from '@connector-kit/connector';
import { copyAddressToClipboard, copyToClipboard } from '@connector-kit/connector';
await copyAddressToClipboard(address);
await copyToClipboard(text);
import {
getClusterRpcUrl,
getClusterExplorerUrl,
getTransactionUrl,
getAddressUrl,
isMainnetCluster,
isDevnetCluster
} from '@connector-kit/connector';
const rpcUrl = getClusterRpcUrl(cluster);
const explorerUrl = getClusterExplorerUrl(cluster);
const txUrl = getTransactionUrl(cluster, signature);
const addrUrl = getAddressUrl(cluster, address);
import type {
// Configuration
ConnectorConfig,
DefaultConfigOptions,
ExtendedConnectorConfig,
UnifiedConfig,
MobileWalletAdapterConfig,
// State & Info
ConnectorState,
ConnectorSnapshot,
WalletInfo,
AccountInfo,
ConnectorHealth, // NEW!
// Events
ConnectorEvent, // NEW!
ConnectorEventListener, // NEW!
// Transaction Signing
TransactionSigner, // NEW!
TransactionSignerConfig, // NEW!
TransactionSignerCapabilities, // NEW!
SignedTransaction, // NEW!
// Connection Pooling
ConnectionLike, // NEW!
ConnectionPoolOptions, // NEW!
ConnectionPoolStats, // NEW!
// Wallet Adapter Compat
WalletAdapterCompatible, // NEW!
WalletAdapterCompatOptions, // NEW!
// Wallet Standard
Wallet,
WalletAccount,
// Clusters
SolanaCluster,
SolanaClusterId,
// Storage
StorageAdapter,
// Hook Returns
UseClusterReturn,
UseAccountReturn,
UseWalletInfoReturn,
UseTransactionSignerReturn, // NEW!
// Errors
WalletError
} from '@connector-kit/connector';
| Component | Size (gzipped) | Tree-Shakeable |
|---|---|---|
| Base Connector | ~45KB | ✅ |
| + Polyfills | +2KB | ❌ (auto-included) |
| + Transaction Signer | +3KB | ✅ |
| + Connection Pool | +1.5KB | ✅ |
| + Debug Panel | +2KB | ✅ (dev-only) |
| + Event System | +0.5KB | ✅ |
| + Compat Layer | +2KB | ✅ |
Total: ~48-53KB for typical production usage
Enhanced support for:
Automatic polyfills ensure compatibility across all environments.
Using the wallet-adapter compatibility bridge for gradual migration:
// Before (wallet-adapter)
import { useWallet } from '@solana/wallet-adapter-react';
const { publicKey, sendTransaction } = useWallet();
await sendTransaction(tx, connection);
// After (connector-kit)
import { useTransactionSigner } from '@connector-kit/connector';
const { signer } = useTransactionSigner();
await signer.signAndSendTransaction(tx);
// Or use compatibility bridge for existing integrations
import { createWalletAdapterCompat } from '@connector-kit/connector/compat';
const walletAdapter = createWalletAdapterCompat(signer, { disconnect });
// Pass walletAdapter to existing wallet-adapter code
Check out the examples directory for:
pnpm install # Install dependencies
pnpm build # Build package
pnpm dev # Development mode with watch
pnpm type-check # TypeScript validation
pnpm lint # Lint code
pnpm size # Check bundle size
Compatible with all Wallet Standard compliant wallets:
MIT
Built with ❤️ and attention to detail
FAQs
Headless wallet connector client and React provider built on Wallet Standard
We found that @connector-kit/connector demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Product
Socket Firewall Free is now bundled into Docker Hardened Images, adding build-time and dependency-install supply chain protection on top of hardened base images for Node.js, Python, and Rust.
Security News
Season’s greetings from Socket, and here’s to a calm end of year: clean dependencies, boring pipelines, no surprises.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.