From 654e462652026d2beeecf27f11a121eb72b51d5a Mon Sep 17 00:00:00 2001
From: Ricardo Ferrari <495887+rferrari@users.noreply.github.com>
Date: Fri, 6 Mar 2026 07:06:20 -0300
Subject: [PATCH] docs: add for Aioha in Next.js App Router
Added a guide on using Aioha with Next.js App Router.
---
docs/framework/nextjs.md | 197 +++++++++++++++++++++++++++++++++++++++
1 file changed, 197 insertions(+)
create mode 100644 docs/framework/nextjs.md
diff --git a/docs/framework/nextjs.md b/docs/framework/nextjs.md
new file mode 100644
index 0000000..26542d5
--- /dev/null
+++ b/docs/framework/nextjs.md
@@ -0,0 +1,197 @@
+# Using Aioha with Next.js (App Router)
+
+This guide shows how to use **Aioha Core** inside a modern **Next.js App Router** application.
+
+Because Next.js uses **Server Components by default**, Aioha must be initialized **only on the client**.
+
+---
+
+# Install
+
+```bash
+pnpm add @aioha/aioha
+````
+
+If you want to use the optional React UI components:
+
+```bash
+pnpm add @aioha/react-ui
+```
+
+---
+
+# Project Structure
+
+Example structure:
+
+```
+app
+ ├ layout.tsx
+ ├ page.tsx
+ ├ providers
+ │ └ AiohaProvider.tsx
+ └ components
+ └ LoginButton.tsx
+```
+
+---
+
+# Create Aioha Provider
+
+Since Aioha interacts with browser wallets like **Hive Keychain**, it must run **client-side only**.
+
+Create a provider component.
+
+`app/providers/AiohaProvider.tsx`
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import { Aioha } from "@aioha/aioha";
+import { AiohaProvider as Provider } from "@aioha/react-ui";
+
+const aioha = new Aioha();
+
+export default function AiohaProvider({
+ children,
+}: {
+ children: React.ReactNode;
+}) {
+ useEffect(() => {
+ aioha.setup();
+ }, []);
+
+ return {children};
+}
+```
+
+---
+
+# Wrap Your App
+
+Wrap the provider in your root layout.
+
+`app/layout.tsx`
+
+```tsx
+import "./globals.css";
+import "@aioha/react-ui/dist/build.css";
+
+import AiohaProvider from "./providers/AiohaProvider";
+
+export default function RootLayout({
+ children,
+}: {
+ children: React.ReactNode;
+}) {
+ return (
+
+
+
+ {children}
+
+
+
+ );
+}
+```
+
+---
+
+# Login Button Example
+
+`app/components/LoginButton.tsx`
+
+```tsx
+"use client";
+
+import { useAioha } from "@aioha/react-ui";
+
+export default function LoginButton() {
+ const { aioha, user } = useAioha();
+
+ async function login() {
+ await aioha.login();
+ }
+
+ return (
+
+ );
+}
+```
+
+---
+
+# Using the Component
+
+`app/page.tsx`
+
+```tsx
+import LoginButton from "./components/LoginButton";
+
+export default function Home() {
+ return (
+
+ Hive Login Example
+
+
+ );
+}
+```
+
+---
+
+# Important Notes
+
+## Client Components Required
+
+Any component using:
+
+```
+useAioha()
+aioha.login()
+```
+
+must include:
+
+```
+"use client"
+```
+
+because Hive wallet integrations require browser APIs.
+
+---
+
+## SSR Considerations
+
+Next.js renders components on the server by default.
+
+To prevent errors:
+
+* Initialize Aioha inside `useEffect`
+* Use client components for authentication UI
+
+---
+
+## Optional CSS
+
+If you use the React UI modal, include:
+
+```
+import "@aioha/react-ui/dist/build.css";
+```
+
+inside your layout.
+
+---
+
+# Summary
+
+When using Aioha with Next.js:
+
+* Initialize Aioha inside a **client provider**
+* Wrap the app in that provider
+* Use **client components** for login UI