From 565f7232fa92b716d15d8cf3634139665c0678d6 Mon Sep 17 00:00:00 2001
From: Xiaoteng152 <1170511756@qq.com>
Date: Mon, 29 Jun 2026 19:36:48 +0800
Subject: [PATCH] docs: document Next.js Wagmi SSR setup
---
.changeset/next-wagmi-ssr-docs.md | 5 ++
examples/next-wagmi-app-router/README.md | 86 ++++++++++++++-----
.../next-wagmi-app-router/eslint.config.mjs | 12 +++
.../next-wagmi-app-router/next.config.mjs | 11 +++
examples/next-wagmi-app-router/package.json | 14 ++-
.../next-wagmi-app-router/src/app/layout.tsx | 7 +-
.../next-wagmi-app-router/src/config/index.ts | 3 +-
packages/adapters/wagmi/README.md | 10 +++
8 files changed, 122 insertions(+), 26 deletions(-)
create mode 100644 .changeset/next-wagmi-ssr-docs.md
create mode 100644 examples/next-wagmi-app-router/eslint.config.mjs
diff --git a/.changeset/next-wagmi-ssr-docs.md b/.changeset/next-wagmi-ssr-docs.md
new file mode 100644
index 0000000000..7c72ad36fa
--- /dev/null
+++ b/.changeset/next-wagmi-ssr-docs.md
@@ -0,0 +1,5 @@
+---
+'@reown/appkit-adapter-wagmi': patch
+---
+
+Document Next.js App Router SSR setup and optional connector build configuration.
diff --git a/examples/next-wagmi-app-router/README.md b/examples/next-wagmi-app-router/README.md
index e215bc4ccf..94433ea57c 100644
--- a/examples/next-wagmi-app-router/README.md
+++ b/examples/next-wagmi-app-router/README.md
@@ -1,36 +1,82 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# AppKit Next.js Wagmi Example (App Router)
+
+Next.js App Router example using `@reown/appkit` with `@reown/appkit-adapter-wagmi`, including SSR via `cookieToInitialState` and `WagmiProvider`.
+
+## Stack
+
+- Next.js 16 (Turbopack by default)
+- wagmi 2.x
+- `@reown/appkit` + `@reown/appkit-adapter-wagmi`
## Getting Started
-First, run the development server:
+```bash
+# From the monorepo root
+pnpm install
+pnpm build
+
+# Copy env and set your WalletConnect Cloud project ID
+cp examples/next-wagmi-app-router/.env.example examples/next-wagmi-app-router/.env.local
+
+# Run the example
+pnpm --filter @examples/next-wagmi-app-router dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Build
```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+# Turbopack (Next.js 16 default)
+pnpm --filter @examples/next-wagmi-app-router build
+
+# Webpack
+pnpm --filter @examples/next-wagmi-app-router exec next build --webpack
```
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## SSR Setup
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+1. Pass `ssr: true` to `WagmiAdapter`.
+2. Read cookies in a Server Component layout and pass them to a client `ContextProvider`.
+3. Use `cookieToInitialState` + `WagmiProvider` in the client provider.
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+See `src/app/layout.tsx`, `src/context/index.tsx`, and `src/config/index.ts`.
-## Learn More
+## Next.js Config: Optional Connector Dependencies
+
+`WagmiAdapter` can load connectors from `@wagmi/connectors` (Safe, Coinbase, Base Account, etc.). The `@wagmi/connectors` package references optional wallet SDKs that Next.js 16 may resolve at build time.
+
+### Recommended: install optional peer dependencies
+
+This example installs the optional packages below so `next build` succeeds with Turbopack and Webpack. Remove packages you do not use only if you also configure bundler stubs.
+
+| Connector | Package |
+| --------- | ------- |
+| Base Account | `@base-org/account` |
+| Coinbase Wallet | `@coinbase/wallet-sdk` |
+| Gemini | `@gemini-wallet/core` |
+| MetaMask SDK | `@metamask/sdk` |
+| Porto | `porto` |
+| Safe App | `@safe-global/safe-apps-provider`, `@safe-global/safe-apps-sdk` |
-To learn more about Next.js, take a look at the following resources:
+AppKit's WalletConnect flow uses `@walletconnect/universal-provider` (via AppKit). You do not need `@walletconnect/ethereum-provider` unless you use the wagmi WalletConnect connector directly.
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+### Alternative: stub uninstalled packages
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+If you prefer not to install unused wallet SDKs, stub those packages in your bundler config. Webpack users can use `webpack.externals` or `resolve.alias`. Turbopack users can use `turbopack.resolveAlias`, but the stub must expose any named exports that `@wagmi/connectors` imports.
-## Deploy on Vercel
+Installing the optional packages above is simpler for this example. See [wevm/wagmi#4887](https://github.com/wevm/wagmi/issues/4887) and [wevm/wagmi#4906](https://github.com/wevm/wagmi/issues/4906).
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+### Next.js 16 bundler notes
+
+- Next.js 16 defaults to Turbopack. If you define a `webpack` config, also set `turbopack: {}` (or migrate settings to `turbopack.resolveAlias`).
+- `transpilePackages` includes AppKit and wagmi packages for App Router compatibility.
+
+## wagmi v3
+
+This example targets wagmi v2, which matches `@reown/appkit-adapter-wagmi` peer dependencies today. wagmi v3 uses the same optional-dependency model with stricter install requirements — see [wagmi v3 migration](https://wagmi.sh/react/guides/migrate-from-v2-to-v3).
+
+## Learn More
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- [AppKit Next.js docs](https://docs.reown.com/appkit/next/core/installation)
+- [wagmi SSR](https://wagmi.sh/react/guides/ssr)
diff --git a/examples/next-wagmi-app-router/eslint.config.mjs b/examples/next-wagmi-app-router/eslint.config.mjs
new file mode 100644
index 0000000000..b1509a312a
--- /dev/null
+++ b/examples/next-wagmi-app-router/eslint.config.mjs
@@ -0,0 +1,12 @@
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+const eslintConfig = [
+ ...nextVitals,
+ ...nextTs,
+ {
+ ignores: ['.next/**', 'out/**', 'build/**', 'next-env.d.ts']
+ }
+]
+
+export default eslintConfig
diff --git a/examples/next-wagmi-app-router/next.config.mjs b/examples/next-wagmi-app-router/next.config.mjs
index 55057d93bf..3a8f264893 100644
--- a/examples/next-wagmi-app-router/next.config.mjs
+++ b/examples/next-wagmi-app-router/next.config.mjs
@@ -1,5 +1,16 @@
/** @type {import('next').NextConfig} */
const nextConfig = {
+ transpilePackages: [
+ '@reown/appkit',
+ '@reown/appkit-adapter-wagmi',
+ 'wagmi',
+ '@wagmi/core',
+ '@wagmi/connectors'
+ ],
+
+ // Required in Next.js 16 when a `webpack` config is present (Turbopack is the default bundler).
+ turbopack: {},
+
webpack: config => {
config.externals.push('pino-pretty', 'lokijs', 'encoding')
return config
diff --git a/examples/next-wagmi-app-router/package.json b/examples/next-wagmi-app-router/package.json
index 1d1722561d..7dd759b5b0 100644
--- a/examples/next-wagmi-app-router/package.json
+++ b/examples/next-wagmi-app-router/package.json
@@ -6,15 +6,23 @@
"dev": "next dev",
"build": "next build",
"start": "next start",
- "lint": "next lint"
+ "lint": "eslint ."
},
"dependencies": {
+ "@base-org/account": "2.4.0",
+ "@coinbase/wallet-sdk": "4.3.6",
+ "@gemini-wallet/core": "0.3.2",
+ "@metamask/sdk": "0.33.1",
"@reown/appkit": "workspace:*",
"@reown/appkit-adapter-wagmi": "workspace:*",
+ "@safe-global/safe-apps-provider": "0.18.6",
+ "@safe-global/safe-apps-sdk": "9.1.0",
"@tanstack/react-query": "5.75.5",
+ "@wagmi/connectors": "5.11.2",
"@wagmi/core": "2.22.1",
- "next": "14.2.35",
+ "next": "16.2.6",
"next-themes": "0.4.6",
+ "porto": "0.2.35",
"react": "19.1.2",
"react-dom": "19.1.2",
"viem": "2.45.0",
@@ -25,7 +33,7 @@
"@types/react": "19.1.15",
"@types/react-dom": "19.1.9",
"esbuild": "0.25.1",
- "eslint-config-next": "14.1.0",
+ "eslint-config-next": "16.2.6",
"typescript": "5.9.2"
}
}
diff --git a/examples/next-wagmi-app-router/src/app/layout.tsx b/examples/next-wagmi-app-router/src/app/layout.tsx
index 9b363bc6b5..0dad109296 100755
--- a/examples/next-wagmi-app-router/src/app/layout.tsx
+++ b/examples/next-wagmi-app-router/src/app/layout.tsx
@@ -1,4 +1,5 @@
import { Metadata } from 'next'
+import { headers } from 'next/headers'
import ContextProvider from '@/context'
@@ -33,11 +34,13 @@ export const metadata: Metadata = {
}
}
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+ const cookies = (await headers()).get('cookie')
+
return (
- {children}
+ {children}
)
diff --git a/examples/next-wagmi-app-router/src/config/index.ts b/examples/next-wagmi-app-router/src/config/index.ts
index 9c4a0aab22..0a49d67d6f 100755
--- a/examples/next-wagmi-app-router/src/config/index.ts
+++ b/examples/next-wagmi-app-router/src/config/index.ts
@@ -22,7 +22,8 @@ export const networks = [mainnet, polygon, arbitrum, optimism] as [
// Setup wagmi adapter
export const wagmiAdapter = new WagmiAdapter({
networks,
- projectId
+ projectId,
+ ssr: true
})
// Create modal
diff --git a/packages/adapters/wagmi/README.md b/packages/adapters/wagmi/README.md
index 724430ea18..40741166cf 100644
--- a/packages/adapters/wagmi/README.md
+++ b/packages/adapters/wagmi/README.md
@@ -41,3 +41,13 @@ Refer to the "Features" section of the [AppKit docs](https://docs.reown.com/appk
> [!NOTE]
> If you are using Web3Modal v1–v5, please use our [migration guides](https://docs.reown.com/appkit/upgrade/to-reown-appkit-web#migrate-from-web3modal-v5-to-reown-appkit).
+
+## Next.js SSR (App Router)
+
+When using `WagmiAdapter` with Next.js App Router:
+
+1. Set `ssr: true` on `WagmiAdapter`.
+2. Pass request cookies into `cookieToInitialState(wagmiAdapter.wagmiConfig, cookies)` inside a client provider wrapped by `WagmiProvider`.
+3. Configure Next.js to stub or install optional `@wagmi/connectors` peer dependencies (Safe, Coinbase, Base Account, etc.) so `next build` succeeds under Turbopack and Webpack.
+
+See the full working example and config reference in [`examples/next-wagmi-app-router`](../../examples/next-wagmi-app-router/README.md).