For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Configuration Options

Network Configuration

Fee Delegation

Configure transaction fee sponsorship:

Login Methods

Configure available authentication methods with a flexible grid layout. Each entry pins a method, an optional gridColumn (1–4) controlling how many of the 4 columns the button spans, and an optional isPrimary flag that promotes the button to the recommended CTA (filled inverted surface + "recommended" green dot). If no entry sets isPrimary, the kit falls back to highlighting the first visible method. Only one button per grid is primary; isPrimary on the more footer link is ignored. The filled treatment currently supports veworld, google, apple, and github.

Defaults (when loginMethods is omitted):

  • With privy: [veworld, google, apple, more]

  • Without privy: [veworld, sync2, wallet-connect]

Gating: granular wallet methods (veworld, sync2, wallet-connect) only render when their source is also in dappKit.allowedWallets.

For the full layout, theming and migration guide, see Login Customization.

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.

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:

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

Privy Integration (Optional)

Most social logins work without your own Privy account — the kit routes Google / Apple / X / Discord / GitHub / TikTok / LINE through VeChain's whitelabel cross-app popup automatically. Pass the privy prop only if you need email, passkey, SMS, additional OAuth providers, or want the login flow to render entirely inside your dApp instead of in a popup window.

To enable those flows with your own Privy account:

Ecosystem Apps Configuration

Customize which ecosystem apps appear in the login modal:

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

Last updated