> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurumsdk.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Next.js
> Integrate Aurum into a Next.js App Router app
This guide covers Next.js with the App Router. Aurum is browser-only (Shadow DOM, `localStorage`, EIP-1193 events) so the integration centers around getting the `'use client'` boundary right. A short [Pages Router note](#pages-router) is at the bottom.
## Install
```bash pnpm theme={null}
pnpm add @aurum-sdk/core @aurum-sdk/hooks
```
```bash npm theme={null}
npm install @aurum-sdk/core @aurum-sdk/hooks
```
```bash yarn theme={null}
yarn add @aurum-sdk/core @aurum-sdk/hooks
```
```bash bun theme={null}
bun add @aurum-sdk/core @aurum-sdk/hooks
```
Requires React 18 or 19 and Next.js 13.4+ (App Router).
## 1. Create the Aurum instance
```typescript lib/aurum.ts theme={null}
import { Aurum } from '@aurum-sdk/core';
export const aurum = new Aurum({
brand: { appName: 'My App' },
wallets: {
embedded: { projectId: process.env.NEXT_PUBLIC_CDP_PROJECT_ID! },
walletConnect: { projectId: process.env.NEXT_PUBLIC_REOWN_PROJECT_ID! },
},
});
```
Use `NEXT_PUBLIC_*` env vars — both project IDs are needed in the browser. Never put a server-only secret here.
The `Aurum` constructor is **SSR-safe** — it guards `window` / `localStorage` access internally — so importing this module from a Server Component will not throw. But the modal, hooks, and event listeners only run in the browser, so any component that *uses* Aurum must be a Client Component.
## 2. Create a client-side provider
The `AurumProvider` itself is a client boundary, so it lives in its own `'use client'` file.
```tsx app/providers.tsx theme={null}
'use client';
import { AurumProvider } from '@aurum-sdk/hooks';
import { aurum } from '@/lib/aurum';
export function Providers({ children }: { children: React.ReactNode }) {
return {children};
}
```
## 3. Wrap the root layout
```tsx app/layout.tsx theme={null}
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`layout.tsx` itself stays a Server Component — only the `Providers` wrapper crosses into the client.
## 4. Build a connect button
Any component that calls Aurum hooks needs `'use client'`.
```tsx app/components/ConnectButton.tsx theme={null}
'use client';
import { useAccount, useConnect, useDisconnect } from '@aurum-sdk/hooks';
export function ConnectButton() {
const { publicAddress, isConnected, isInitializing } = useAccount();
const { connect, isPending, error } = useConnect();
const { disconnect } = useDisconnect();
if (isInitializing) return ;
if (isConnected) {
return (
}
);
}
```
`isInitializing` is `true` while Aurum restores any persisted connection. Always render a placeholder — otherwise users see a flash of the disconnected state on every page load.
You can drop `` into any Server Component page; the `'use client'` boundary stays inside the component tree without infecting the rest of the page.
```tsx app/page.tsx theme={null}
import { ConnectButton } from './components/ConnectButton';
export default function Home() {
return (
Welcome
);
}
```
## 5. Sign a message
```bash theme={null}
pnpm add viem
```
```tsx app/components/SignMessageButton.tsx theme={null}
'use client';
import { createWalletClient, custom } from 'viem';
import { useAccount } from '@aurum-sdk/hooks';
import { aurum } from '@/lib/aurum';
const walletClient = createWalletClient({
transport: custom(aurum.rpcProvider),
});
export function SignMessageButton() {
const { publicAddress, isConnected } = useAccount();
async function signMessage() {
if (!publicAddress) return;
const signature = await walletClient.signMessage({
account: publicAddress as `0x${string}`,
message: 'Hello from Aurum!',
});
console.log('signature', signature);
}
return (
);
}
```
See the [Viem](/api-reference/integrations/viem), [Ethers v5](/api-reference/integrations/ethers-v5), or [Ethers v6](/api-reference/integrations/ethers-v6) pages for the full surface.
## Server-side caveats
A few things that **don't** work the way you might expect:
* **Server Components cannot use Aurum hooks.** Wallet state lives in the browser. Read it from a Client Component and pass it down via context or props.
* **Middleware and Route Handlers cannot read wallet state.** They run on the server, where there is no wallet connection. If you need server-side auth, sign a SIWE message client-side and verify it in a Route Handler.
* **Don't dynamic-import Aurum with `ssr: false`** unless you're seeing a real hydration warning. The SDK is SSR-safe out of the box and `ssr: false` would defeat the persisted-connection restore on first paint.
* **Don't construct multiple `Aurum` instances per route.** The constructor returns the existing instance and warns if the new config differs. Keep one `lib/aurum.ts` import everywhere.
## Pages Router
The Pages Router setup is the same idea — wrap `` in `_app.tsx`:
```tsx pages/_app.tsx theme={null}
import type { AppProps } from 'next/app';
import { AurumProvider } from '@aurum-sdk/hooks';
import { aurum } from '@/lib/aurum';
export default function App({ Component, pageProps }: AppProps) {
return (
);
}
```
You don't need `'use client'` directives in the Pages Router — every component is rendered on the client by default.
## Next steps
Theme the modal
Build a fully custom UI
Hooks API reference