Next.js (App Router)

butr is a client-side wallet library — it touches window, wallet extensions, and localStorage. Under the App Router that means the provider must be a client component.

The `"use client"` boundary

The demo-next reference is EVM-only (no @usebutr/svm or @usebutr/wallets in the bundle) — see EVM-only setup for the install, chain list, and bundle rationale. This page covers only what is specific to the App Router. The provider module starts with "use client":

src/wallet-provider.tsx

"use client";

import type { ReactNode } from "react";
import { createWalletSource } from "@usebutr/core";
import { WalletManagerProvider, useDiscoveredWallets } from "@usebutr/react";
import { discoverEvmAdapters } from "@usebutr/evm";

// EVM-only: @usebutr/react + @usebutr/evm. No @usebutr/svm / @usebutr/wallets in the
// bundle — discovery is a WalletSource built from the EVM discoverer.
const evmDiscovery = createWalletSource(discoverEvmAdapters);

const WalletProvider = ({ children }: { children: ReactNode }) => (
  <WalletManagerProvider discovery={evmDiscovery} storageKeyPrefix="butr-demo">
    {children}
  </WalletManagerProvider>
);

export { WalletProvider, useDiscoveredWallets };

Mount it in the root layout (a Server Component importing a Client Component is fine):

src/app/layout.tsx

import type { ReactNode } from "react";
import { WalletProvider } from "../wallet-provider";

const RootLayout = ({ children }: { children: ReactNode }) => (
  <html lang="en">
    <body>
      <WalletProvider>{children}</WalletProvider>
    </body>
  </html>
);

export default RootLayout;

Any page using butr hooks (useConnectWallet, useActiveWallet, …) must also be "use client".

Chains without `@usebutr/wallets`

EVM-only setups don't bundle @usebutr/wallets. Pull the chain list from @usebutr/evm directly:

import { EVM_CHAINS_LIST } from "@usebutr/evm";
const CHAINS_BY_PLATFORM = { evm: EVM_CHAINS_LIST, svm: [] as const };

Why this keeps Solana out of the bundle is covered in EVM-only setup.

Want EVM + SVM instead?

Use autoDiscovery() from @usebutr/wallets in a "use client" module — same as Vite, just with the directive at the top. See Provider setup for the full pattern.

Source: apps/demo-next/src/wallet-provider.tsx in the butr repository. Run pnpm dev --filter=demo-next → http://localhost:3000.

Next.js (App Router)

The "use client" boundary

Chains without @usebutr/wallets

Want EVM + SVM instead?

On this page

The `"use client"` boundary

Chains without `@usebutr/wallets`