> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 Widget Light

> @lifi/widget-light 的安装与快速入门指南

几分钟即可上手 Widget Light。核心包除了 React 之外没有任何依赖 -- 你只需为想要支持的区块链生态系统添加对等依赖。

## 核心包

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light
  ```
</CodeGroup>

## 生态系统依赖

为你想要支持的每个区块链生态系统安装对等依赖。你只需要安装应用实际用到的生态系统。

### EVM（Ethereum）

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```
</CodeGroup>

### Solana

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @wallet-standard/base
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @wallet-standard/base
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @wallet-standard/base
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @wallet-standard/base
  ```
</CodeGroup>

### Bitcoin

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @bigmi/client @bigmi/react
  ```
</CodeGroup>

### Sui

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @mysten/dapp-kit-react
  ```
</CodeGroup>

### Tron

Tron 处理器与具体库无关 — 你需要显式传入钱包状态。使用该 API 只需要 `@lifi/widget-light`。如果你按照文档记录的方式使用 [`@tronweb3/tronwallet-adapter-react-hooks`](https://www.npmjs.com/package/@tronweb3/tronwallet-adapter-react-hooks) 进行集成，请将其与核心包一起安装：

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```
</CodeGroup>

### 所有生态系统

一次性安装所有内容：

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query @wallet-standard/base @bigmi/client @bigmi/react @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query @wallet-standard/base @bigmi/client @bigmi/react @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query @wallet-standard/base @bigmi/client @bigmi/react @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query @wallet-standard/base @bigmi/client @bigmi/react @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks
  ```
</CodeGroup>

## 快速入门 -- 仅 EVM（wagmi）

这是使用 wagmi 面向 EVM 链的最小设置。它假设你的应用中已经配置了 wagmi provider。

### 1. 配置你的钱包 provider

像平常一样设置 wagmi。Widget Light 会从你现有的 wagmi 上下文中读取钱包状态。

```tsx theme={"system"}
// providers/WalletProvider.tsx
import type { FC, PropsWithChildren } from 'react'
import { createClient, http } from 'viem'
import { arbitrum, base, mainnet, optimism, polygon } from 'viem/chains'
import { createConfig, WagmiProvider } from 'wagmi'
import { injected } from 'wagmi/connectors'

const config = createConfig({
  chains: [mainnet, arbitrum, optimism, base, polygon],
  connectors: [injected()],
  client({ chain }) {
    return createClient({ chain, transport: http() })
  },
  multiInjectedProviderDiscovery: true,
  ssr: false,
})

export const WalletProvider: FC<PropsWithChildren> = ({ children }) => (
  <WagmiProvider config={config}>{children}</WagmiProvider>
)
```

### 2. 设置 provider 树

```tsx theme={"system"}
// main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import React from 'react'
import ReactDOM from 'react-dom/client'
import { App } from './App'
import { WalletProvider } from './providers/WalletProvider'

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <App />
      </WalletProvider>
    </QueryClientProvider>
  </React.StrictMode>
)
```

### 3. 渲染 widget

```tsx theme={"system"}
// App.tsx
import { LiFiWidgetLight } from '@lifi/widget-light'
import type { WidgetLightConfig } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useMemo } from 'react'

const widgetConfig: WidgetLightConfig = {
  integrator: 'your-project-name',
  variant: 'wide',
  theme: {
    container: {
      border: '1px solid rgb(234, 234, 234)',
      borderRadius: '16px',
    },
  },
}

export function App() {
  const ethHandler = useEthereumIframeHandler()
  const handlers = useMemo(() => [ethHandler], [ethHandler])

  return (
    <LiFiWidgetLight
      config={widgetConfig}
      handlers={handlers}
      autoResize
    />
  )
}
```

widget 在 iframe 内渲染，所有 EVM 交易都通过你的 wagmi 托管钱包进行签名。

## 完整的多生态系统设置

要在支持 EVM 的同时支持 Solana、Bitcoin、Sui 和 Tron，请安装额外的处理器对等依赖，并将所有处理器传递给 widget。

```tsx theme={"system"}
import { LiFiWidgetLight } from '@lifi/widget-light'
import type { WidgetLightConfig } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useSolanaIframeHandler } from '@lifi/widget-light/solana'
import { useBitcoinIframeHandler } from '@lifi/widget-light/bitcoin'
import { useSuiIframeHandler } from '@lifi/widget-light/sui'
import { useTronIframeHandler } from '@lifi/widget-light/tron'
import { useMemo } from 'react'

const widgetConfig: WidgetLightConfig = {
  integrator: 'your-project-name',
  variant: 'wide',
}

export function App() {
  // EVM -- reads wallet state from wagmi context automatically
  const ethHandler = useEthereumIframeHandler()

  // Solana -- pass wallet state explicitly (library-agnostic)
  const solHandler = useSolanaIframeHandler({
    address: solanaAddress,       // string | null
    connected: solanaConnected,   // boolean
    wallet: solanaWallet,         // Wallet from @wallet-standard/base | null
  })

  // Bitcoin -- reads from @bigmi/react context automatically
  const btcHandler = useBitcoinIframeHandler()

  // Sui -- reads from @mysten/dapp-kit-react context automatically
  const suiHandler = useSuiIframeHandler()

  // Tron -- pass wallet state explicitly (library-agnostic)
  const tronHandler = useTronIframeHandler({
    address: tronAddress,         // string | null
    connected: tronConnected,     // boolean
    adapter: tronAdapter,         // TronAdapter | null
  })

  const handlers = useMemo(
    () => [ethHandler, solHandler, btcHandler, suiHandler, tronHandler],
    [ethHandler, solHandler, btcHandler, suiHandler, tronHandler]
  )

  return (
    <LiFiWidgetLight
      config={widgetConfig}
      handlers={handlers}
      autoResize
    />
  )
}
```

<Note>
  只包含你需要的处理器。如果你只支持 EVM 和 Solana，则传入 `[ethHandler, solHandler]`。未使用的生态系统包会被完全从你的 bundle 中 tree-shake 掉。
</Note>

## TypeScript 支持

Widget Light 使用 TypeScript 编写，并提供完整的类型定义。所有配置选项、事件 payload 和处理器接口都是完全类型化的：

```tsx theme={"system"}
import type { WidgetLightConfig } from '@lifi/widget-light'

const config: WidgetLightConfig = {
  // TypeScript will provide autocomplete and type checking
  integrator: 'my-dapp',
  appearance: 'dark',
  variant: 'wide',
}
```