Balance: {formatKLV(balance)} KLV
)
}
```
**Use cases:**
- React dApp development
- State management for balances and transactions
- Staking operations UI
- Real-time transaction monitoring
**Note:** Install separately with `npm install @klever/connect-react` (not included in the main package to keep bundle size small for non-React projects)
## Choosing the Right Package
### Should I use `@klever/connect` or individual packages?
#### Use `@klever/connect` (unified package) when:
✅ **You're building a complete dApp**
```typescript
// Everything in one import
import { KleverProvider, Wallet, Contract, parseKLV } from '@klever/connect'
```
✅ **You want the simplest developer experience**
- Single package to install and update
- No need to manage multiple versions
- All exports in one place
✅ **Bundle size is not a critical concern**
- Server-side applications
- Desktop apps (Electron)
- Internal tools
#### Use individual packages when:
✅ **You need minimal bundle size**
```typescript
// Only import what you need
import { parseKLV } from '@klever/connect-core'
import { KleverProvider } from '@klever/connect-provider'
```
✅ **You're building a library**
- Avoid forcing users to install unused dependencies
- Better dependency management
✅ **You only need specific functionality**
- Backend service that only reads data → `@klever/connect-provider`
- Utility library for address validation → `@klever/connect-core`
- Transaction signing service → `@klever/connect-crypto` + `@klever/connect-transactions`
### Bundle Size Comparison
| Package | Approximate Size | What's Included |
| ------------------------------ | ---------------- | ------------------------ |
| `@klever/connect-core` | ~15 KB | Types, utilities, errors |
| `@klever/connect-provider` | ~25 KB | Network communication |
| `@klever/connect-transactions` | ~20 KB | Transaction building |
| `@klever/connect-wallet` | ~18 KB | Wallet management |
| `@klever/connect-contracts` | ~22 KB | Smart contracts |
| `@klever/connect-crypto` | ~30 KB | Cryptographic operations |
| `@klever/connect-encoding` | ~35 KB | Protocol buffers |
| **Full SDK (@klever/connect)** | **~165 KB** | Everything above |
**Tree-shaking benefits:**
Modern bundlers (webpack 5+, Vite, esbuild) can tree-shake unused exports from `@klever/connect`, so you only pay for what you use!
```typescript
// Only KleverProvider code is included in your bundle
import { KleverProvider } from '@klever/connect'
```
## Complete Example
Here's a complete dApp example showing how all packages work together:
```typescript
import {
// Provider & Network
KleverProvider,
NETWORKS,
// Wallet
Wallet,
createWallet,
// Transaction Building
TransactionBuilder,
// Smart Contracts
Contract,
ContractFactory,
// Utilities
parseKLV,
formatKLV,
createLogger,
// Types
KleverAddress,
TransactionHash,
// Errors
KleverError,
TransactionError,
} from '@klever/connect'
// Enable logging
const logger = createLogger({ level: 'info' })
// 1. Setup provider
const provider = new KleverProvider({
network: NETWORKS.testnet,
timeout: 30000,
retries: 3,
})
// 2. Create wallet (auto-detects browser/node)
const wallet = createWallet(privateKey, provider)
const address = await wallet.getAddress()
logger.info(`Wallet address: ${address}`)
// 3. Check balance
const account = await provider.getAccount(address)
logger.info(`Balance: ${formatKLV(account.balance)} KLV`)
// 4. Build and send a simple transfer
async function sendKLV(to: KleverAddress, amount: bigint) {
try {
const tx = await TransactionBuilder.create(provider)
.sender(address)
.transfer({
receiver: to,
amount,
})
.build()
// Sign and broadcast
await tx.sign(wallet.privateKey)
const result = await provider.sendRawTransaction(tx.toHex())
logger.info(`Transaction sent: ${result.hash}`)
// Wait for confirmation
const receipt = await result.wait()
logger.info(`Transaction confirmed in block ${receipt.block}`)
return receipt
} catch (error) {
if (error instanceof TransactionError) {
logger.error(`Transaction failed: ${error.message}`)
}
throw error
}
}
// 5. Deploy a smart contract
async function deployContract(bytecode: string, abi: any, constructorArgs: any[]) {
const factory = new ContractFactory(abi, bytecode, wallet)
const contract = await factory.deploy(...constructorArgs)
logger.info(`Contract deployed at: ${contract.address}`)
return contract
}
// 6. Interact with smart contract
async function interactWithContract(contractAddress: KleverAddress, contractABI: any) {
const contract = new Contract(contractAddress, contractABI, wallet)
// Read data (no gas cost)
const name = await contract.call.name()
const totalSupply = await contract.call.totalSupply()
logger.info(`Token: ${name}, Total Supply: ${totalSupply}`)
// Write data (sends transaction)
const transferTx = await contract.invoke.transfer('klv1recipient...', parseKLV('100'))
const receipt = await transferTx.wait()
// Parse events
const events = await contract.parseEvents(receipt)
events.forEach((event) => {
logger.info(`Event: ${event.name}`, event.args)
})
return receipt
}
// 7. Advanced: Multi-operation transaction
async function complexTransaction() {
const tx = await TransactionBuilder.create(provider)
.sender(address)
.transfer({
receiver: 'klv1recipient1...',
amount: parseKLV('50'),
})
.transfer({
receiver: 'klv1recipient2...',
amount: parseKLV('30'),
assetId: 'MY-TOKEN',
})
.freeze({
amount: parseKLV('100'),
assetId: 'KLV',
})
.build()
await tx.sign(wallet.privateKey)
const result = await provider.sendRawTransaction(tx.toHex())
return result.wait()
}
// 8. Error handling
async function safeOperation() {
try {
await sendKLV('klv1recipient...', parseKLV('1000'))
} catch (error) {
if (error instanceof KleverError) {
switch (error.code) {
case 'INSUFFICIENT_FUNDS':
logger.error('Not enough KLV')
break
case 'INVALID_ADDRESS':
logger.error('Invalid recipient address')
break
case 'NETWORK_ERROR':
logger.error('Network issue, retrying...')
// Implement retry logic
break
default:
logger.error(`Unknown error: ${error.message}`)
}
}
}
}
// Run the example
async function main() {
try {
// Send KLV
await sendKLV('klv1fpwjz234gy8aaae3gx0e8q9f52vymzzn3z5q0s5h60pvktzx0n0qwvtux5', parseKLV('10'))
// Complex transaction
await complexTransaction()
logger.info('All operations completed successfully!')
} catch (error) {
logger.error('Failed:', error)
process.exit(1)
}
}
main()
```
### React dApp Example
```typescript
import { KleverProvider, NETWORKS } from '@klever/connect'
import { KleverContextProvider, useBalance, useTransaction } from '@klever/connect-react'
// 1. Setup provider
const provider = new KleverProvider({ network: NETWORKS.testnet })
// 2. Wrap your app
function App() {
return (