Migrate from v3 to v4

# Core widget only
pnpm add @lifi/widget @tanstack/react-query

# With blockchain providers (recommended)
pnpm add @lifi/widget @lifi/widget-provider-ethereum @lifi/widget-provider-solana @lifi/widget-provider-bitcoin @lifi/widget-provider-sui @lifi/widget-provider-tron wagmi @wagmi/core @bigmi/react bs58 @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks @tanstack/react-query

// Widget v3
import { LiFiWidget } from '@lifi/widget';
import { WagmiProvider } from 'wagmi';

export const WidgetPage = () => {
  return (
    <WagmiProvider config={wagmiConfig}>
      <LiFiWidget integrator="your-dapp" />
    </WagmiProvider>
  );
};

// Widget v4
import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { EthereumProvider } from '@lifi/widget-provider-ethereum';
import { SolanaProvider } from '@lifi/widget-provider-solana';
import { BitcoinProvider } from '@lifi/widget-provider-bitcoin';
import { SuiProvider } from '@lifi/widget-provider-sui';
import { TronProvider } from '@lifi/widget-provider-tron';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider(),
    SolanaProvider(),
    BitcoinProvider(),
    SuiProvider(),
    TronProvider(),
  ],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="your-dapp" config={widgetConfig} />;
};

import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [EthereumProvider()],
};

// Widget v3
const widgetConfig: WidgetConfig = {
  walletConfig: {
    walletConnect: {
      projectId: 'your-project-id',
    },
    coinbase: {
      appName: 'Your App',
    },
  },
};

// Widget v4
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      walletConnect: {
        projectId: 'your-project-id',
      },
      coinbase: {
        appName: 'Your App',
      },
      metaMask: {
        // MetaMask SDK options
      },
      porto: {
        // Porto connector options (EIP-7702)
      },
      baseAccount: {
        // Base Account options
      },
    }),
  ],
};

# Remove old package
pnpm remove @mysten/dapp-kit

# Install new package
pnpm add @mysten/dapp-kit-react

// Widget v3
import { useAvailableChains } from '@lifi/widget';
const { chains } = useAvailableChains();

// Widget v4
import { useWidgetChains } from '@lifi/widget';
import type { WidgetConfig } from '@lifi/widget';
const widgetConfig: WidgetConfig = { integrator: 'your-dapp' };
const { chains } = useWidgetChains(widgetConfig);

// Widget v3
interface WidgetWalletConfig {
  onConnect(): void
  walletConnect?: WalletConnectParameters
  coinbase?: CoinbaseWalletParameters
}

// Widget v4
interface WidgetWalletConfig {
  onConnect?(args?: WalletMenuOpenArgs): void
  walletEcosystemsOrder?: Record<string, ChainType[]>
  usePartialWalletManagement?: boolean
  forceInternalWalletManagement?: boolean
}

// Widget v3
const widgetConfig: WidgetConfig = {
  sdkConfig: {
    executionOptions: {
      disableMessageSigning: true,
    },
  },
};

// Widget v4
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      disableMessageSigning: true,
    }),
  ],
};

// Widget v4
interface WidgetSDKConfig {
  executionOptions?: {
    updateTransactionRequestHook?: (request: TransactionRequest) => Promise<TransactionRequest>
  }
}

// Widget v3 - React Router needed special handling
<BrowserRouter>
  <Routes>
    <Route path="/swap/*" element={<LiFiWidgetPage />} />
  </Routes>
</BrowserRouter>

// Widget v4 - Standard routes work fine
<BrowserRouter>
  <Routes>
    <Route path="/swap" element={<LiFiWidgetPage />} />
  </Routes>
</BrowserRouter>

// Widget v3
navigationRoutes.activeTransactions  // 'active-transactions'
navigationRoutes.transactionHistory  // 'transaction-history'

// Widget v4
navigationRoutes.activities          // 'activities' (replaces both)

// Widget v3
const widgetConfig: WidgetConfig = {
  subvariant: 'split',
  subvariantOptions: {
    split: 'bridge',
  },
};

// Widget v4
const widgetConfig: WidgetConfig = {
  mode: 'split',
  modeOptions: {
    split: 'bridge',
  },
};

// Widget v3
subvariantOptions: {
  custom: 'checkout',  // string shorthand
}

// Widget v4
modeOptions: {
  custom: { type: 'checkout' },  // object with type field
}

// Widget v3
subvariantOptions: {
  wide: {
    disableChainSidebar: true,
  },
}

// Widget v4
hiddenUI: {
  chainSidebar: true,  // Hide the chain sidebar in wide variant
}

// Widget v3
import { DisabledUI, HiddenUI } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  disabledUI: [DisabledUI.ToAddress],
  hiddenUI: [HiddenUI.Appearance, HiddenUI.Language, HiddenUI.PoweredBy],
};

// Widget v4
const widgetConfig: WidgetConfig = {
  disabledUI: { toAddress: true },
  hiddenUI: { appearance: true, language: true, poweredBy: true },
};

// Widget v3
const widgetConfig: WidgetConfig = {
  useRecommendedRoute: true,
};

// Widget v4
const widgetConfig: WidgetConfig = {
  showSingleRoute: true,
};

// Widget v3
const widgetConfig: WidgetConfig = {
  fee: 0.03,
};

// Widget v4
const widgetConfig: WidgetConfig = {
  feeConfig: {
    fee: 0.03,
  },
};

// New in v4 - both tabs with configurable default
modeOptions: {
  split: { defaultTab: 'swap' },
}

// Widget v3 (mitt-style)
type WidgetEvents = {
  availableRoutes: Route[]
  routeExecutionStarted: Route
}

// Widget v4 (eventemitter3-style)
type WidgetEvents = {
  availableRoutes: (data: Route[]) => void
  routeExecutionStarted: (data: Route) => void
}

// Widget v3
interface WalletConnected {
  address?: string
  chainId?: number
  chainType?: ChainType
}

// Widget v4
import { useWalletManagementEvents, WalletManagementEvent } from '@lifi/wallet-management';
import type { WalletConnected } from '@lifi/wallet-management';

interface WalletConnected {
  address: string
  chainId: number
  chainType: ChainType
  connectorId: string
  connectorName: string
}

// Widget v3
type RouteExecutionUpdate = {
  route: Route
  process: Process
}

// Widget v4
type RouteExecutionUpdate = {
  route: Route
  action: ExecutionAction
}

// Widget v3
widgetEvents.on(WidgetEvent.RouteExecutionUpdated, (update) => {
  console.log(update.process);
});

// Widget v4
widgetEvents.on(WidgetEvent.RouteExecutionUpdated, (update) => {
  console.log(update.action);
});