nexus-elements-overview（联系要素概述）

Nexus Elements Overview

Integrate end-to-end in any TS/React app

• Install project deps:

- pnpm add @avail-project/nexus-core wagmi viem lucide-react

• If using wagmi (recommended), also install:

- pnpm add @tanstack/react-query

• Ensure shadcn/ui is initialized (components.json exists) if installing from registry.

Configure registry

• Add this mapping in components.json:

"registries": {
  "@nexus-elements/": "https://elements.nexus.availproject.org/r/{name}.json"
}

Set up SDK + wallet foundation first

• Install and wire nexus-provider before any other element:

- npx shadcn@latest add @nexus-elements/nexus-provider

• Wrap your app with NexusProvider.
• On wallet connect, resolve an EIP-1193 provider and call handleInit(provider).
• Pass config={{network: "mainnet" | "testnet", debug?: boolean}} to NexusProvider when needed.

Minimal provider wrapper

"use client";

import NexusProvider from "@/components/nexus/NexusProvider";

export function AppNexusProvider({ children }: { children: React.ReactNode }) {
  return <NexusProvider config={{ network: "mainnet" }}>{children}</NexusProvider>;
}

Initialize SDK on connect

"use client";

import { useEffect } from "react";
import { useAccount, useConnectorClient } from "wagmi";
import type { EthereumProvider } from "@avail-project/nexus-core";
import { useNexus } from "@/components/nexus/NexusProvider";

export function InitNexusOnConnect() {
  const { status, connector } = useAccount();
  const { data: walletClient } = useConnectorClient();
  const { handleInit } = useNexus();

  useEffect(() => {
    if (status !== "connected") return;

    void (async () => {
      const mobileProvider = walletClient
        ? ({ request: (args: unknown) => walletClient.request(args as never) } as EthereumProvider)
        : undefined;
      const desktopProvider = await connector?.getProvider();
      const provider = mobileProvider ?? (desktopProvider as EthereumProvider | undefined);
      if (!provider || typeof provider.request !== "function") return;
      await handleInit(provider);
    })();
  }, [status, connector, walletClient, handleInit]);

  return null;
}

Install widgets

• Install all widgets:

- npx shadcn@latest add @nexus-elements/all

• Or install individually:

- @nexus-elements/fast-bridge - @nexus-elements/transfer - @nexus-elements/swaps - @nexus-elements/deposit - @nexus-elements/bridge-deposit - @nexus-elements/unified-balance - @nexus-elements/view-history

SDK function map by widget

• FastBridge:

- sdk.bridge - sdk.calculateMaxForBridge - hooks: setOnIntentHook, setOnAllowanceHook - events: NEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETE

• FastTransfer:

- sdk.bridgeAndTransfer - sdk.calculateMaxForBridge - hooks: setOnIntentHook, setOnAllowanceHook - events: NEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETE

• SwapWidget:

- sdk.swapWithExactIn, sdk.swapWithExactOut - hook: setOnSwapIntentHook - event: NEXUS_EVENTS.SWAP_STEP_COMPLETE

• Deposit:

- sdk.swapAndExecute - hook: setOnSwapIntentHook - event: NEXUS_EVENTS.SWAP_STEP_COMPLETE

• BridgeDeposit:

- sdk.simulateBridgeAndExecute - sdk.bridgeAndExecute - hooks: setOnIntentHook, setOnAllowanceHook - events: NEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETE

• UnifiedBalance:

- sdk.getBalancesForBridge, sdk.getBalancesForSwap

• ViewHistory:

- sdk.getMyIntents

Pick the right widget

• Use fast-bridge for self-bridge UX (recipient defaults to connected address).
• Use transfer for bridge-to-recipient UX.
• Use swaps for exact-in and exact-out cross-chain swaps.
• Use deposit for swap + execute integrations where destination token/chain is fixed by product config.
• Use bridge-deposit for bridge + execute integrations with lighter UI and manual execute builder.
• Use unified-balance to show cross-chain balances.
• Use view-history for intent history.

E2E readiness checklist

• Confirm wallet connects and handleInit runs once per session.
• Confirm useNexus().nexusSDK is non-null after connect.
• Confirm balances load (bridgableBalance, swapBalance).
• Confirm intent hooks are populated during preview states.
• Confirm every flow can reach success and emits explorer URLs.
• Confirm disconnect clears SDK state (deinitializeNexus).

Common integration failures

• Invalid provider object:

- Ensure provider has request().

• Widget stuck in preview:

- Ensure hook handlers eventually call allow() or deny().

• Empty balances/history:

- Ensure SDK init finished and wallet is connected on a supported network.