End-to-end integration guide for Nexus Elements in any TypeScript/React codebase. Use when setting up Nexus Elements from scratch, choosing which widget to install, wiring NexusProvider + wallet initialization, or validating bridge/transfer/swap/deposit/history behavior in production-like flows.
pnpm add @avail-project/nexus-core wagmi viem lucide-reactpnpm add @tanstack/react-querycomponents.json exists) if installing from registry.components.json:"registries": {
"@nexus-elements/": "https://elements.nexus.availproject.org/r/{name}.json"
}
nexus-provider before any other element:
npx shadcn@latest add @nexus-elements/nexus-providerNexusProvider.handleInit(provider).config={{ network: "mainnet" | "testnet", debug?: boolean }} to NexusProvider when needed."use client";
import NexusProvider from "@/components/nexus/NexusProvider";
export function AppNexusProvider({ children }: { children: React.ReactNode }) {
return <NexusProvider config={{ network: "mainnet" }}>{children}</NexusProvider>;
}
"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;
}
npx shadcn@latest add @nexus-elements/all@nexus-elements/fast-bridge@nexus-elements/transfer@nexus-elements/swaps@nexus-elements/deposit@nexus-elements/bridge-deposit@nexus-elements/unified-balance@nexus-elements/view-historyFastBridge:
sdk.bridgesdk.calculateMaxForBridgesetOnIntentHook, setOnAllowanceHookNEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETEFastTransfer:
sdk.bridgeAndTransfersdk.calculateMaxForBridgesetOnIntentHook, setOnAllowanceHookNEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETESwapWidget:
sdk.swapWithExactIn, sdk.swapWithExactOutsetOnSwapIntentHookNEXUS_EVENTS.SWAP_STEP_COMPLETEDeposit:
sdk.swapAndExecutesetOnSwapIntentHookNEXUS_EVENTS.SWAP_STEP_COMPLETEBridgeDeposit:
sdk.simulateBridgeAndExecutesdk.bridgeAndExecutesetOnIntentHook, setOnAllowanceHookNEXUS_EVENTS.STEPS_LIST, NEXUS_EVENTS.STEP_COMPLETEUnifiedBalance:
sdk.getBalancesForBridge, sdk.getBalancesForSwapViewHistory:
sdk.getMyIntentsfast-bridge for self-bridge UX (recipient defaults to connected address).transfer for bridge-to-recipient UX.swaps for exact-in and exact-out cross-chain swaps.deposit for swap + execute integrations where destination token/chain is fixed by product config.bridge-deposit for bridge + execute integrations with lighter UI and manual execute builder.unified-balance to show cross-chain balances.view-history for intent history.handleInit runs once per session.useNexus().nexusSDK is non-null after connect.bridgableBalance, swapBalance).deinitializeNexus).request().allow() or deny().