Overview
Client-side Ethereum Kit for React and browser environments
React API
The React entry point provides client-side functionality for integrating Ethereum wallets with the Shelby Protocol. It's designed for browser applications where users connect their Ethereum wallets (MetaMask, Coinbase Wallet, etc.) via wagmi to interact with Shelby storage.
Installation
npm install @shelby-protocol/ethereum-kitYou'll also need wagmi and its dependencies for wallet connections:
npm install wagmi viem @tanstack/react-queryFor simplicity, also install the Shelby react package for react hooks helpers:
npm install @shelby-protocol/reactWallet Setup
The Ethereum Kit works with wagmi-based wallet libraries:
- RainbowKit - Popular, beautiful wallet connection UI
- Web3Modal - WalletConnect's official modal
- ConnectKit - Family's wallet connector
- Dynamic - Multi-chain wallet integration
All of these use wagmi under the hood, so you can use useWalletClient() directly with the Ethereum Kit.
See your wallet library's documentation for setup instructions. Once configured, the useWalletClient() hook provides the wallet needed by Ethereum Kit.
Usage
Import from the @shelby-protocol/ethereum-kit/react entry point:
"use client";
import { useStorageAccount, Network } from "@shelby-protocol/ethereum-kit/react";
import { useUploadBlobs } from "@shelby-protocol/react";
import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { useWalletClient } from "wagmi";
function MyComponent() {
// Use wagmi wallet hook
const { data: wallet } = useWalletClient();
// Initiate Shelby client
const shelbyClient = new ShelbyClient({
network: Network.SHELBYNET,
apiKey: "AG-***",
});
// Use Shelby ethereum-kit hook
const { storageAccountAddress, signAndSubmitTransaction } = useStorageAccount({
client: shelbyClient,
wallet,
});
// Use Shelby react package upload blob hook
const { mutateAsync: uploadBlobs } = useUploadBlobs({
client: shelbyClient,
});
const handleUpload = async () => {
await uploadBlobs({
signer: { account: storageAccountAddress, signAndSubmitTransaction },
blobs: [
{
blobName: "example.txt",
blobData: new Uint8Array([1, 2, 3]),
},
],
// 30 days from now in microseconds
expirationMicros: (1000 * 60 * 60 * 24 * 30 + Date.now()) * 1000,
});
};
return (
<div>
<p>Storage Account: {storageAccountAddress?.toString()}</p>
<button onClick={handleUpload}>Upload</button>
</div>
);
}When to Use React
Use the React entry point when you:
- Building browser-based dApps
- Users connect via Ethereum wallet extensions (MetaMask, Coinbase Wallet, etc.)
- Need wallet-based signing (user approves each transaction)
- Building React/Next.js applications
For server-side applications with direct wallet access, use the Node.js entry point instead.
Exports
The @shelby-protocol/ethereum-kit/react entry point exports:
| Export | Description |
|---|---|
useStorageAccount | React hook for storage account operations |
EthereumWallet | Type for viem WalletClient |
UseStorageAccountParams | Type for hook parameters |
UseStorageAccountResult | Type for hook return value |
SignAndSubmitTransactionInput | Type for transaction input |
SignTransactionInput | Type for sign-only transaction input |
SubmitTransactionInput | Type for submit-only transaction input |
Network | Network configuration constants |
Key Differences from Node.js
| Feature | Node.js (/node) | React (/react) |
|---|---|---|
| Signing | Direct wallet signing | Wallet popup for user approval |
| Storage Account | ShelbyStorageAccount class | Derived via hook |
| Environment | Server-side | Browser |
| Wallet Access | Full wallet (with private key) | Public address only (wallet holds key) |