NexusProvider Setup

Wrap your application with the NexusProvider to enable the Nexus Widget.

Nexus Widget relies on the NexusProvider — a React context provider that initializes the Nexus SDK and shares wallet state across your component tree. Without it, the widget cannot sign transactions or read on-chain data. In this step you will:

Wrap your application layout with the provider
Create a small helper component that initializes Nexus when a wallet connects

Step 1 — Wrap your app with NexusProvider

Open your root layout file (or the highest-level client boundary in your app) and wrap the children with NexusProvider imported from @avail-project/widgets.

app/providers.tsx

"use client";
import { NexusProvider } from "@avail-project/widgets";
 
export default function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  return <NexusProvider config={{ network: "mainnet" }}>{children}</NexusProvider>;
}

Then use this component in your root layout:

app/layout.tsx

import Providers from "./providers";
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Step 2 — Initialize Nexus on wallet connect

Create an InitNexusOnConnect component that listens for wallet connection events and hands the provider instance to the SDK via useNexus() from @avail-project/widgets.

components/InitNexusOnConnect.tsx

"use client";
import { useEffect } from "react";
import { useAccount, useConnectorClient } from "wagmi";
import type { EthereumProvider } from "@avail-project/nexus-core";
import { useNexus } from "@avail-project/widgets";
 
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;
}

Where to place the provider

NexusProvider must be rendered inside your wallet provider (e.g. wagmi's WagmiProvider) because it needs access to the connected wallet. A typical nesting order is:WagmiProvider → QueryClientProvider → ConnectKitProvider → NexusProvider → {children}

Render `InitNexusOnConnect` alongside the provider

Add InitNexusOnConnect inside your providers component so it runs automatically when the wallet connects:

app/providers.tsx

"use client";
import { NexusProvider } from "@avail-project/widgets";
import { InitNexusOnConnect } from "@/components/InitNexusOnConnect";
 
export default function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <NexusProvider config={{ network: "mainnet" }}>
      <InitNexusOnConnect />
      {children}
    </NexusProvider>
  );
}

Client components only

Both NexusProvider and InitNexusOnConnect must be client components (marked with "use client") because they use React hooks and browser APIs.

Next step

The provider is configured and the SDK will initialize as soon as the user connects a wallet. You are now ready to render your first component.

Your First Widget

Go to next step. Rendering the Nexus Widget.

How is this guide?

Installation

Your First Widget

Step 1 — Wrap your app with NexusProvider Step 2 — Initialize Nexus on wallet connect Step 1 — Wrap your app with NexusProvider Step 2 — Initialize Nexus on wallet connect Render InitNexusOnConnect alongside the provider Next step

Edit in GitHub

"use client"; import { NexusProvider } from "@avail-project/widgets"; export default function Providers({ children, }: { children: React.ReactNode; }) { return <NexusProvider config={{ network: "mainnet" }}>{children}</NexusProvider>; }

import Providers from "./providers"; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <html lang="en"> <body> <Providers>{children}</Providers> </body> </html> ); }

"use client"; import { useEffect } from "react"; import { useAccount, useConnectorClient } from "wagmi"; import type { EthereumProvider } from "@avail-project/nexus-core"; import { useNexus } from "@avail-project/widgets"; 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; }

"use client"; import { NexusProvider } from "@avail-project/widgets"; import { InitNexusOnConnect } from "@/components/InitNexusOnConnect"; export default function Providers({ children, }: { children: React.ReactNode; }) { return ( <NexusProvider config={{ network: "mainnet" }}> <InitNexusOnConnect /> {children} </NexusProvider> ); }

Search Documentation

NexusProvider Setup

Step 1 — Wrap your app with NexusProvider

Step 2 — Initialize Nexus on wallet connect

Render InitNexusOnConnect alongside the provider

Next step

Search Documentation

NexusProvider Setup

Step 1 — Wrap your app with NexusProvider

Step 2 — Initialize Nexus on wallet connect

Render InitNexusOnConnect alongside the provider

Next step

Render `InitNexusOnConnect` alongside the provider

Render `InitNexusOnConnect` alongside the provider