reown-com · Xiaoteng152 · Jun 29, 2026
diff --git a/.changeset/next-wagmi-ssr-docs.md 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 (
     <html lang="en">
       <body>
-        <ContextProvider cookies={null}>{children}</ContextProvider>
+        <ContextProvider cookies={cookies}>{children}</ContextProvider>
       </body>
     </html>
   )

diff --git 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
@@ -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).