Provider Configuration

This guide covers how to set up and configure the VeChainKitProvider in your application.

Basic Setup

Wrap your app with the VeChainKitProvider:

'use client';

import { VeChainKitProvider } from "@vechain/vechain-kit";

export function Providers({ children }) {
  return (
    <VeChainKitProvider>
      {children}
    </VeChainKitProvider>
  );
}

Next.js Configuration

For Next.js applications, dynamically import the provider to avoid SSR issues:

import dynamic from 'next/dynamic';

const VeChainKitProvider = dynamic(
  async () => (await import('@vechain/vechain-kit')).VeChainKitProvider,
  { ssr: false }
);

export function Providers({ children }) {
  return (
    <VeChainKitProvider>
      {children}
    </VeChainKitProvider>
  );
}

Complete Configuration Example

Here's a comprehensive example with all available options:

'use client';

import { VeChainKitProvider } from "@vechain/vechain-kit";

export function VeChainKitProviderWrapper({ children }: { children: React.ReactNode }) {
  return (
    <VeChainKitProvider
      // Network Configuration
      network={{
        type: "test", // "main" | "test" | "solo"
      }}
      
      // UI Configuration
      darkMode={false}
      language="en"
      theme={{
          backgroundColor: 'black'
      }}
      
      // Login Modal UI Customization
      loginModalUI={{
        logo: '/your-logo.png',
        description: 'Welcome to our DApp',
      }}
      
      // Login Methods Configuration
      loginMethods={[
        { method: "vechain", gridColumn: 4 },
        { method: "dappkit", gridColumn: 4 },
      ]}
      
      // Sponsor transactions
      feeDelegation={{
          delegatorUrl: process.env.NEXT_PUBLIC_DELEGATOR_URL!,
      }}
      
      // Wallet Connection Configuration
      dappKit={{
        allowedWallets: ["veworld", "wallet-connect", "sync2"],
        walletConnectOptions: {
          projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
          metadata: {
            name: "Your DApp Name",
            description: "Your DApp description visible in wallets",
            url: typeof window !== "undefined" ? window.location.origin : "",
            icons: ["https://your-domain.com/logo.png"],
          },
        },
      }}

      // Contract Address Overrides (optional)
      // Override default contract addresses for custom deployments
      contractAddresses={{
        b3trContractAddress: "0x...",
        vot3ContractAddress: "0x...",
      }}
    >
      {children}
    </VeChainKitProvider>
  );
}

Configuration Options

Network Configuration

network: {
  type: "main" | "test" | "solo" // Select mainnet or testnet or solo
}

Fee Delegation

Configure transaction fee sponsorship:

feeDelegation: {
  delegatorUrl: string,           // Fee delegation service URL
}

Login Methods

Configure available authentication methods with a flexible grid layout:

loginMethods: [
  // Always available methods
  { method: "vechain", gridColumn: 4 },    // VeChain social login
  { method: "dappkit", gridColumn: 4 },    // VeChain wallets
  { method: "ecosystem", gridColumn: 4 },  // Ecosystem apps (Mugshot, Cleanify, Greencart, etc.)
  
  // Privy-dependent methods (require your own privy configuration)
  { method: "email", gridColumn: 2 },      // Email login
  { method: "passkey", gridColumn: 2 },    // Passkey authentication
  { method: "google", gridColumn: 4 },     // Google OAuth
  { method: "more", gridColumn: 2 },       // Additional Privy methods
]

Grid Layout: The gridColumn property determines the width of each login option in the modal (based on a 4-column grid).

Contract Address Overrides

Override default contract addresses for custom deployments on solo or testnet. Only the provided fields are overridden; the rest use the network defaults.

contractAddresses: Partial<AppConfig>  // Any field from AppConfig can be overridden

This is useful when you deploy your own contract instances (e.g., B3TR, VOT3) and need the kit to use those addresses instead of the built-in defaults:

<VeChainKitProvider
  network={{ type: "solo" }}
  contractAddresses={{
    b3trContractAddress: "0x026771d1be764467f8bdb78bb230df10c924b00d",
    vot3ContractAddress: "0xf7a08af15cb3501feee53ebe11f4428a966fa459",
    // You can override any AppConfig field — see Configs page for the full list
  }}
>
  {children}
</VeChainKitProvider>

To access the merged config (network defaults + your overrides) in your components, use the useAppConfig hook:

import { useAppConfig } from '@vechain/vechain-kit';

function MyComponent() {
  const config = useAppConfig();
  console.log(config.b3trContractAddress); // Your overridden address
}

Privy Integration (Optional)

To enable social login methods with your own Privy account:

<VeChainKitProvider
  privy={{
    appId: "your-privy-app-id",
    clientId: "your-privy-client-id",
    // Additional Privy configuration
  }}
  loginMethods={[
    // Now you can use Privy-dependent methods
    { method: "email", gridColumn: 2 },
    { method: "google", gridColumn: 4 },
    { method: "passkey", gridColumn: 2 },
  ]}
>
  {children}
</VeChainKitProvider>

Ecosystem Apps Configuration

Customize which ecosystem apps appear in the login modal:

<VeChainKitProvider
  loginMethods={[
    { method: "ecosystem", gridColumn: 4 }
  ]}
  ecosystemApps={{
    allowedApps: ["app-id-1", "app-id-2"], // Find app IDs in Privy dashboard
  }}
>
  {children}
</VeChainKitProvider>

Best Practices

1. Dynamic Import: Always use dynamic import in Next.js to avoid SSR issues

2. Environment Variables: Store sensitive configuration in environment variables

3. Fee Delegation: Consider your fee delegation strategy based on user experience needs

4. Login Methods: Choose login methods that match your target audience

5. Metadata: Provide clear app metadata for wallet connection requests

Next Steps

• Implement Authentication Methods

• Customize UI Theme

• Handle Wallet Interactions