@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-nextjs-patterns/SKILL.md

@@ -1,899 +0,0 @@
----
-name: cometchat-nextjs-patterns
-description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into Next.js projects (App Router and Pages Router). Covers SSR prevention, provider setup, route placement, API routes, and common pitfalls."
-license: "MIT"
-compatibility: "Node.js >=18; React >=18; Next.js >=13; @cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "chat cometchat nextjs next react ssr app-router pages-router patterns"
----
-
-> **Ground truth:** `@cometchat/chat-uikit-react@^6` (+ `@cometchat/calls-sdk-javascript@^5`) — installed package types + `ui-kit/react`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
-
-## Purpose
-
-This skill teaches Claude how to integrate CometChat into a Next.js project. Next.js is the most complex framework to integrate with because of Server-Side Rendering (SSR) and the Server Component / Client Component boundary. Every CometChat component is browser-only -- getting this wrong is the #1 source of integration failures.
-
-**Read these companion skills first:**
-- `cometchat-core` -- initialization, login, CSS, provider pattern, anti-patterns
-- `cometchat-components` -- component catalog and composition patterns
-- `cometchat-placement` -- WHERE to put chat (route, modal, drawer, embedded)
-
-This skill covers the HOW for Next.js specifically.
-
----
-
-## 1. Project detection
-
-A project uses Next.js when `package.json` has `next` as a dependency.
-
-### Detecting App Router vs Pages Router
-
-Both may coexist in a project. Check which is primary:
-
-```bash
-# App Router: look for app/ directory with layout.tsx
-ls app/layout.tsx app/layout.jsx 2>/dev/null
-
-# Pages Router: look for pages/ directory with _app.tsx
-ls pages/_app.tsx pages/_app.jsx pages/_app.js 2>/dev/null
-```
-
-**If `app/layout.tsx` exists, treat the project as App Router.** Even if `pages/` also exists, App Router is the primary routing mechanism in modern Next.js.
-
-**If only `pages/` exists, treat the project as Pages Router.**
-
----
-
-## 2. Critical: SSR prevention
-
-**Every file that imports from `@cometchat/chat-uikit-react` MUST prevent server-side rendering.** CometChat components access `window`, `document`, and WebSocket APIs during import -- not just during render, but at import time. If Next.js tries to import these modules on the server, the build crashes with `ReferenceError: window is not defined`.
-
-### App Router: "use client" directive
-
-Add `"use client"` as the FIRST line of every file that imports CometChat:
-
-```tsx
-"use client";
-
-import { CometChatConversations } from "@cometchat/chat-uikit-react";
-// This file only runs in the browser
-```
-
-**Common mistake:** Putting `"use client"` AFTER imports. It must be the very first line, before any import statements.
-
-```tsx
-// WRONG -- "use client" is not the first line
-import React from "react";
-"use client"; // too late, has no effect
-
-// CORRECT
-"use client";
-import React from "react";
-```
-
-### App Router: dynamic import from a Client Component (Next.js 15+ rule)
-
-> ⚠️ **Next.js 15+ change (verified by runtime smoke 2026-06-02):** `dynamic(..., { ssr: false })` is **FORBIDDEN in Server Components** — Next.js 15+ throws a build error. The page that owns the dynamic-import MUST be a Client Component (`"use client"` at line 1). Otherwise the build fails with `Ecmascript file had an error` even if everything else is correct.
-
-```tsx
-// app/messages/page.tsx
-"use client";   // ← REQUIRED in Next.js 15+ when using `dynamic({ ssr: false })`
-import dynamic from "next/dynamic";
-
-const ChatView = dynamic(() => import("../../components/ChatView"), {
-  ssr: false,
-  loading: () => <div>Loading chat...</div>,
-});
-
-export default function MessagesPage() {
-  return <ChatView />;
-}
-```
-
-The `ChatView` component file itself must also have `"use client"` at the top. Both ends of the dynamic-import boundary need the directive.
-
-**If you cannot make the page a Client Component** (because it needs server data-fetching), wrap your data-fetching in a separate Server Component sibling and pass results down via props to a Client Component that owns the CometChat subtree.
-
-**Build still fails after applying both `"use client"` and `dynamic(... ssr:false)`?** Add `export const dynamic = "force-dynamic";` at the top of the page to opt out of static prerendering entirely (or `export const runtime = "edge";` for edge runtime). This is sometimes needed in Next.js 16 even with everything else correct — verified during 2026-06-02 smoke against Next.js 16.2.7. Skill-side suspicion: kit's module-eval-time `window` references still trip static prerender even via dynamic boundary.
-
-### Pages Router: dynamic import
-
-In the Pages Router, every page can potentially run on the server. Use `next/dynamic`:
-
-```tsx
-// pages/messages.tsx
-import dynamic from "next/dynamic";
-
-const ChatView = dynamic(() => import("../components/ChatView"), {
-  ssr: false,
-  loading: () => <div>Loading chat...</div>,
-});
-
-export default function MessagesPage() {
-  return <ChatView />;
-}
-```
-
----
-
-## 3. CometChatProvider for Next.js (App Router)
-
-### Full implementation
-
-```tsx
-// app/providers/CometChatProvider.tsx
-"use client";
-
-import React, { useEffect, useState, createContext, useContext } from "react";
-import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
-
-interface CometChatContextValue {
-  isReady: boolean;
-  error: string | null;
-}
-
-const CometChatContext = createContext<CometChatContextValue>({
-  isReady: false,
-  error: null,
-});
-
-export const useCometChat = () => useContext(CometChatContext);
-
-// Module-level state prevents both double-init AND double-login in React
-// StrictMode. Without the loginInFlight guard, a second mount calls
-// login() while the first is still pending and the SDK throws
-// "Please wait until the previous login request ends."
-let initialized = false;
-let loginInFlight: Promise<unknown> | null = null;
-
-async function ensureLoggedIn(
-  uid: string,
-  authToken?: string,
-): Promise<void> {
-  const existing = await CometChatUIKit.getLoggedinUser();
-  if (existing) return;
-  if (loginInFlight) {
-    await loginInFlight;
-    return;
-  }
-  loginInFlight = authToken
-    ? CometChatUIKit.loginWithAuthToken(authToken)
-    : CometChatUIKit.login(uid);
-  try {
-    await loginInFlight;
-  } finally {
-    loginInFlight = null;
-  }
-}
-
-interface CometChatProviderProps {
-  children: React.ReactNode;
-}
-
-export function CometChatProvider({ children }: CometChatProviderProps) {
-  const [isReady, setIsReady] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    async function setup() {
-      try {
-        if (!initialized) {
-          initialized = true;
-
-          const settings = new UIKitSettingsBuilder()
-            .setAppId(process.env.NEXT_PUBLIC_COMETCHAT_APP_ID!)
-            .setRegion(process.env.NEXT_PUBLIC_COMETCHAT_REGION!)
-            .setAuthKey(process.env.NEXT_PUBLIC_COMETCHAT_AUTH_KEY!)
-            .subscribePresenceForAllUsers()
-            .build();
-
-          await CometChatUIKit.init(settings);
-        }
-
-        await ensureLoggedIn("cometchat-uid-1"); // DEVELOPMENT ONLY — see cometchat-production skill
-
-        setIsReady(true);
-      } catch (e) {
-        setError(formatCometChatError(e)); // from cometchat-core §6 errors.ts — NOT String(e),
-                                           // which renders "[object Object]" on kit errors (ENG-35719)
-      }
-    }
-
-    setup();
-  }, []);
-
-  if (error) {
-    return (
-      <div style={{ color: "red", padding: 16, fontFamily: "monospace" }}>
-        CometChat Error: {error}
-      </div>
-    );
-  }
-
-  if (!isReady) return null;
-
-  return (
-    <CometChatContext.Provider value={{ isReady, error }}>
-      {children}
-    </CometChatContext.Provider>
-  );
-}
-```
-
-### Where to mount: Option A -- Global (chat available everywhere)
-
-Wrap the entire app in `app/layout.tsx`. The layout itself is a Server Component, but the provider is a Client Component via `"use client"` in its file:
-
-```tsx
-// app/layout.tsx (Server Component)
-import { CometChatProvider } from "./providers/CometChatProvider";
-import "./globals.css";
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <CometChatProvider>
-          {children}
-        </CometChatProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**Note:** Importing a `"use client"` component from a Server Component is fine. Next.js renders the Server Component on the server and defers the Client Component to the browser. The `CometChatProvider` only runs its `useEffect` (and init) in the browser.
-
-> ⚠️ **Option A REQUIRES `force-dynamic` on the layout (verified — real build, Next 16.2.9 + kit 6.5.1).** Mounting the provider in `app/layout.tsx` pulls the kit module into the layout's module graph, so `next build` evaluates it during the **static prerender** of *every* route — including `/` (which imports no CometChat code) and the framework-generated `/_not-found` — and crashes with `ReferenceError: window is not defined`. `"use client"` does NOT prevent this in Next 16. The per-page `export const dynamic = "force-dynamic"` from §"Build still fails…" cannot fix it, because `/_not-found` has no page file to annotate. **The fix is to put the directive on the LAYOUT, where it cascades to all routes including `/_not-found`:**
-> ```tsx
-> // app/layout.tsx — add this alongside the provider mount
-> export const dynamic = "force-dynamic";
-> ```
-> If you would rather keep static prerendering for non-chat routes, use **Option B** (scoped route group) so `/` and `/_not-found` never import the kit — that is the cleaner choice for marketing/SSG-heavy sites.
-
-### Where to mount: Option B -- Scoped (chat only on chat routes)
-
-Use a route group to scope the provider to chat-related routes:
-
-```
-app/
-  layout.tsx          <-- no CometChat here
-  page.tsx            <-- home page, no chat overhead
-  (chat)/
-    layout.tsx        <-- CometChatProvider wraps only this group
-    messages/
-      page.tsx        <-- chat page
-    inbox/
-      page.tsx        <-- another chat page
-```
-
-```tsx
-// app/(chat)/layout.tsx
-import { CometChatProvider } from "../providers/CometChatProvider";
-
-export default function ChatLayout({ children }: { children: React.ReactNode }) {
-  return <CometChatProvider>{children}</CometChatProvider>;
-}
-```
-
-Option B is better for performance: CometChat's SDK and WebSocket connection are only loaded when the user visits a chat route. Option A is simpler and ensures incoming call notifications work everywhere.
-
----
-
-## 4. CometChatProvider for Next.js (Pages Router)
-
-In the Pages Router, mount the provider in `_app.tsx`. Use dynamic import to prevent SSR:
-
-```tsx
-// pages/_app.tsx
-import type { AppProps } from "next/app";
-import dynamic from "next/dynamic";
-import "../styles/globals.css";
-
-const CometChatProvider = dynamic(
-  () => import("../components/CometChatProvider").then((mod) => mod.CometChatProvider),
-  { ssr: false }
-);
-
-export default function App({ Component, pageProps }: AppProps) {
-  return (
-    <CometChatProvider>
-      <Component {...pageProps} />
-    </CometChatProvider>
-  );
-}
-```
-
-The provider implementation is the same as section 3, but the file lives at `components/CometChatProvider.tsx` (no `"use client"` needed in Pages Router -- `ssr: false` handles SSR prevention).
-
----
-
-## 5. Route placement (App Router)
-
-Next.js App Router uses file-system routing. Creating a file at the right path automatically creates the route.
-
-### Create the chat page
-
-```tsx
-// app/messages/page.tsx
-"use client";
-
-import { useState } from "react";
-import {
-  CometChatConversations,
-  CometChatMessageHeader,
-  CometChatMessageList,
-  CometChatMessageComposer,
-} from "@cometchat/chat-uikit-react";
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-
-export default function MessagesPage() {
-  const [selectedUser, setSelectedUser] = useState<CometChat.User>();
-  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();
-
-  function handleConversationClick(conversation: CometChat.Conversation) {
-    const entity = conversation.getConversationWith();
-    if (entity instanceof CometChat.User) {
-      setSelectedUser(entity);
-      setSelectedGroup(undefined);
-    } else if (entity instanceof CometChat.Group) {
-      setSelectedUser(undefined);
-      setSelectedGroup(entity);
-    }
-  }
-
-  return (
-    <div style={{ display: "flex", height: "100vh" }}>
-      <div style={{ width: "360px", borderRight: "1px solid #eee" }}>
-        <CometChatConversations onItemClick={handleConversationClick} />
-      </div>
-      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
-        {(selectedUser || selectedGroup) ? (
-          <>
-            {selectedUser && <CometChatMessageHeader user={selectedUser} />}
-            {selectedGroup && <CometChatMessageHeader group={selectedGroup} />}
-            {selectedUser && <CometChatMessageList user={selectedUser} hideReplyInThreadOption={true} />}
-            {selectedGroup && <CometChatMessageList group={selectedGroup} hideReplyInThreadOption={true} />}
-            {selectedUser && <CometChatMessageComposer user={selectedUser} />}
-            {selectedGroup && <CometChatMessageComposer group={selectedGroup} />}
-          </>
-        ) : (
-          <div style={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "center", color: "#999" }}>
-            Select a conversation to start chatting
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-```
-
-This page is accessible at `/messages`. No router configuration needed -- Next.js handles it via the file system.
-
-### Add a navigation link
-
-Find the layout's nav component and add a link:
-
-```tsx
-import Link from "next/link";
-
-// In the nav, alongside existing links:
-<Link href="/messages">Messages</Link>
-```
-
-**Important:** Use Next.js's `<Link>` component (from `next/link`), not a plain `<a>` tag or React Router's `<Link>`. Next.js's Link handles client-side navigation and prefetching.
-
----
-
-## 6. Route placement (Pages Router)
-
-### Create the chat page
-
-```tsx
-// pages/messages.tsx
-import dynamic from "next/dynamic";
-
-const ChatView = dynamic(() => import("../components/ChatView"), {
-  ssr: false,
-  loading: () => (
-    <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100vh" }}>
-      Loading chat...
-    </div>
-  ),
-});
-
-export default function MessagesPage() {
-  return <ChatView />;
-}
-```
-
-The `ChatView` component contains the actual CometChat composition (see `cometchat-placement` for patterns). It is dynamically imported with `ssr: false` to prevent server rendering.
-
-### ChatView implementation
-
-```tsx
-// components/ChatView.tsx
-import { useState } from "react";
-import {
-  CometChatConversations,
-  CometChatMessageHeader,
-  CometChatMessageList,
-  CometChatMessageComposer,
-} from "@cometchat/chat-uikit-react";
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-
-export default function ChatView() {
-  const [selectedUser, setSelectedUser] = useState<CometChat.User>();
-  const [selectedGroup, setSelectedGroup] = useState<CometChat.Group>();
-
-  function handleConversationClick(conversation: CometChat.Conversation) {
-    const entity = conversation.getConversationWith();
-    if (entity instanceof CometChat.User) {
-      setSelectedUser(entity);
-      setSelectedGroup(undefined);
-    } else if (entity instanceof CometChat.Group) {
-      setSelectedUser(undefined);
-      setSelectedGroup(entity);
-    }
-  }
-
-  return (
-    <div style={{ display: "flex", height: "100vh" }}>
-      <div style={{ width: "360px", borderRight: "1px solid #eee" }}>
-        <CometChatConversations onItemClick={handleConversationClick} />
-      </div>
-      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
-        {selectedUser && (
-          <>
-            <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} hideReplyInThreadOption={true} />
-            <CometChatMessageComposer user={selectedUser} />
-          </>
-        )}
-        {selectedGroup && (
-          <>
-            <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} hideReplyInThreadOption={true} />
-            <CometChatMessageComposer group={selectedGroup} />
-          </>
-        )}
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-## 7. Modal/drawer placement
-
-### App Router
-
-Create a Client Component for the drawer:
-
-```tsx
-// components/ChatDrawer.tsx
-"use client";
-
-import { useEffect, useState } from "react";
-import {
-  CometChatMessageHeader,
-  CometChatMessageList,
-  CometChatMessageComposer,
-} from "@cometchat/chat-uikit-react";
-import { CometChat } from "@cometchat/chat-sdk-javascript";
-
-interface ChatDrawerProps {
-  isOpen: boolean;
-  onClose: () => void;
-  targetUserId?: string;
-}
-
-export function ChatDrawer({ isOpen, onClose, targetUserId }: ChatDrawerProps) {
-  const [user, setUser] = useState<CometChat.User>();
-
-  useEffect(() => {
-    if (!isOpen || !targetUserId) return;
-    CometChat.getUser(targetUserId).then(setUser);
-  }, [isOpen, targetUserId]);
-
-  if (!isOpen) return null;
-
-  return (
-    <>
-      <div onClick={onClose} style={{ position: "fixed", inset: 0, zIndex: 999, backgroundColor: "rgba(0,0,0,0.3)" }} />
-      <div style={{
-        position: "fixed", top: 0, right: 0, bottom: 0, width: "400px", zIndex: 1000,
-        backgroundColor: "#fff", boxShadow: "-4px 0 20px rgba(0,0,0,0.15)",
-        display: "flex", flexDirection: "column",
-      }}>
-        <div style={{ display: "flex", justifyContent: "space-between", padding: "12px", borderBottom: "1px solid #eee" }}>
-          <span style={{ fontWeight: 600 }}>Chat</span>
-          <button onClick={onClose} style={{ background: "none", border: "none", cursor: "pointer" }}>X</button>
-        </div>
-        {user && (
-          <>
-            <CometChatMessageHeader user={user} />
-            <div style={{ flex: 1, overflow: "hidden" }}>
-              <CometChatMessageList user={user} hideReplyInThreadOption={true} />
-            </div>
-            <CometChatMessageComposer user={user} />
-          </>
-        )}
-      </div>
-    </>
-  );
-}
-```
-
-**Mounting the drawer:** The drawer component has `"use client"`, so it can be imported from either Server or Client Components. Import it in the layout or any page:
-
-```tsx
-// In a Server Component layout -- this works because ChatDrawer is "use client"
-import { ChatDrawer } from "../components/ChatDrawer";
-
-// But state management (isOpen) must be in a Client Component.
-// Option 1: wrap in a small client component
-// Option 2: use a client-side context for drawer state
-```
-
-For state lifting across the Server/Client boundary, create a small Client Component wrapper:
-
-```tsx
-// components/ChatDrawerTrigger.tsx
-"use client";
-
-import { useState } from "react";
-import { ChatDrawer } from "./ChatDrawer";
-
-export function ChatDrawerTrigger({ targetUserId }: { targetUserId: string }) {
-  const [isOpen, setIsOpen] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setIsOpen(true)}>Message</button>
-      <ChatDrawer isOpen={isOpen} onClose={() => setIsOpen(false)} targetUserId={targetUserId} />
-    </>
-  );
-}
-```
-
-### Pages Router
-
-Use `dynamic` import for the drawer/modal component:
-
-```tsx
-import dynamic from "next/dynamic";
-
-const ChatDrawer = dynamic(() => import("../components/ChatDrawer").then(m => m.ChatDrawer), {
-  ssr: false,
-});
-```
-
-See `cometchat-placement` for complete modal and drawer implementations.
-
----
-
-## 8. API route for production auth
-
-Next.js can serve as both frontend and backend. Use an API route to generate CometChat auth tokens server-side.
-
-### App Router API route
-
-```tsx
-// app/api/cometchat-token/route.ts
-import { NextRequest, NextResponse } from "next/server";
-
-const COMETCHAT_APP_ID = process.env.COMETCHAT_APP_ID!;       // server-only, no NEXT_PUBLIC_ prefix
-const COMETCHAT_REGION = process.env.COMETCHAT_REGION!;        // server-only
-const COMETCHAT_AUTH_TOKEN = process.env.COMETCHAT_AUTH_TOKEN!; // server-only secret
-
-export async function POST(request: NextRequest) {
-  try {
-    const { uid } = await request.json();
-
-    if (!uid || typeof uid !== "string") {
-      return NextResponse.json({ error: "uid is required" }, { status: 400 });
-    }
-
-    const response = await fetch(
-      `https://${COMETCHAT_APP_ID}.api-${COMETCHAT_REGION}.cometchat.io/v3/users/${uid}/auth_tokens`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          apiKey: COMETCHAT_AUTH_TOKEN,
-          appId: COMETCHAT_APP_ID,
-        },
-        body: JSON.stringify({}),
-      }
-    );
-
-    if (!response.ok) {
-      const error = await response.text();
-      return NextResponse.json({ error }, { status: response.status });
-    }
-
-    const data = await response.json();
-    return NextResponse.json({ token: data.data.authToken });
-  } catch (error) {
-    return NextResponse.json({ error: String(error) }, { status: 500 });
-  }
-}
-```
-
-### Pages Router API route
-
-```tsx
-// pages/api/cometchat-token.ts
-import type { NextApiRequest, NextApiResponse } from "next";
-
-const COMETCHAT_APP_ID = process.env.COMETCHAT_APP_ID!;
-const COMETCHAT_REGION = process.env.COMETCHAT_REGION!;
-const COMETCHAT_AUTH_TOKEN = process.env.COMETCHAT_AUTH_TOKEN!;
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  if (req.method !== "POST") {
-    return res.status(405).json({ error: "Method not allowed" });
-  }
-
-  try {
-    const { uid } = req.body;
-
-    if (!uid || typeof uid !== "string") {
-      return res.status(400).json({ error: "uid is required" });
-    }
-
-    const response = await fetch(
-      `https://${COMETCHAT_APP_ID}.api-${COMETCHAT_REGION}.cometchat.io/v3/users/${uid}/auth_tokens`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          apiKey: COMETCHAT_AUTH_TOKEN,
-          appId: COMETCHAT_APP_ID,
-        },
-        body: JSON.stringify({}),
-      }
-    );
-
-    if (!response.ok) {
-      const error = await response.text();
-      return res.status(response.status).json({ error });
-    }
-
-    const data = await response.json();
-    return res.status(200).json({ token: data.data.authToken });
-  } catch (error) {
-    return res.status(500).json({ error: String(error) });
-  }
-}
-```
-
-### Environment variables for the API route
-
-Add server-only variables to `.env.local` (no `NEXT_PUBLIC_` prefix -- these must NOT be exposed to the browser):
-
-```env
-# .env.local -- server-only (no NEXT_PUBLIC_ prefix)
-COMETCHAT_APP_ID=your_app_id
-COMETCHAT_REGION=us
-COMETCHAT_AUTH_TOKEN=your_server_auth_token
-
-# Client-side (NEXT_PUBLIC_ prefix)
-NEXT_PUBLIC_COMETCHAT_APP_ID=your_app_id
-NEXT_PUBLIC_COMETCHAT_REGION=us
-NEXT_PUBLIC_COMETCHAT_AUTH_KEY=your_client_auth_key
-```
-
-**Note:** `COMETCHAT_AUTH_TOKEN` (server secret) and `COMETCHAT_AUTH_KEY` (client key) are different values from the CometChat dashboard. The auth token has higher privileges. Never prefix it with `NEXT_PUBLIC_`.
-
----
-
-## 9. Environment variables
-
-### Next.js env var conventions
-
-| Variable | Prefix | Accessible from | File |
-|---|---|---|---|
-| Client-side vars | `NEXT_PUBLIC_` | Browser + Server | `.env.local` |
-| Server-only vars | None | Server only (API routes, Server Components) | `.env.local` |
-
-### .env.local file
-
-```env
-NEXT_PUBLIC_COMETCHAT_APP_ID=your_app_id
-NEXT_PUBLIC_COMETCHAT_REGION=us
-NEXT_PUBLIC_COMETCHAT_AUTH_KEY=your_auth_key
-```
-
-**Access in client code:** `process.env.NEXT_PUBLIC_COMETCHAT_APP_ID`
-
-**Important:** `.env.local` is gitignored by default in Next.js. Unlike Vite, you do not need to manually add it to `.gitignore`.
-
----
-
-## 10. CSS import
-
-### App Router
-
-Import in `app/globals.css` or `app/layout.tsx`:
-
-```css
-/* app/globals.css */
-@import "@cometchat/chat-uikit-react/css-variables.css";
-
-/* your styles below */
-```
-
-Or as a JS import in the root layout:
-
-```tsx
-// app/layout.tsx
-import "@cometchat/chat-uikit-react/css-variables.css";
-import "./globals.css";
-```
-
-### Pages Router
-
-Import in `pages/_app.tsx` or `styles/globals.css`:
-
-```tsx
-// pages/_app.tsx
-import "@cometchat/chat-uikit-react/css-variables.css";
-import "../styles/globals.css";
-```
-
----
-
-## 11. Common pitfalls
-
-### Missing "use client"
-
-**Symptom:** `ReferenceError: window is not defined` or `ReferenceError: document is not defined` during build or at runtime.
-
-**Cause:** A file imports from `@cometchat/chat-uikit-react` without `"use client"` at the top. Next.js tries to render it on the server.
-
-**Fix:** Add `"use client"` as the first line of the file.
-
-### Server/client code mixing
-
-**Symptom:** Build errors about `next/headers`, `cookies()`, or `generateMetadata` in the same file as CometChat imports.
-
-**Cause:** Server-only APIs and client-only APIs cannot coexist in the same file. CometChat requires `"use client"`, but `next/headers` and `cookies()` are server-only.
-
-**Fix:** Split the file. Keep server logic in a Server Component; keep CometChat in a separate `"use client"` component that the Server Component imports.
-
-```tsx
-// app/messages/page.tsx (Server Component -- does data fetching)
-import { cookies } from "next/headers";
-import dynamic from "next/dynamic";
-
-const ChatView = dynamic(() => import("../../components/ChatView"), { ssr: false });
-
-export default async function MessagesPage() {
-  const session = cookies().get("session"); // server-only
-  if (!session) redirect("/login");
-
-  return <ChatView />;
-}
-```
-
-### Image optimization
-
-CometChat renders avatars and media images via its own components. These do not conflict with `next/image`. Do not try to replace CometChat's internal images with `next/image` -- they are managed by the SDK.
-
-### Middleware
-
-CometChat has no middleware requirements. Do not add CometChat-related middleware. If the project has auth middleware (e.g., protecting routes), just ensure the chat route is behind the same auth as the rest of the app.
-
-### ISR/SSG pages with chat
-
-If a page uses static generation (`generateStaticParams`) or ISR, you can still add chat. Wrap the CometChat components in a Client Component. The page's static HTML ships without chat, and the Client Component hydrates and renders chat in the browser:
-
-```tsx
-// app/products/[id]/page.tsx
-export async function generateStaticParams() {
-  // ... returns product IDs for static generation
-}
-
-export default async function ProductPage({ params }: { params: { id: string } }) {
-  const product = await getProduct(params.id);
-
-  return (
-    <div>
-      <h1>{product.name}</h1>
-      <p>{product.description}</p>
-      {/* ChatPanel is "use client" -- renders only in the browser */}
-      <ChatPanel targetUserId={product.sellerId} />
-    </div>
-  );
-}
-```
-
-### Turbopack
-
-Next.js's Turbopack (dev mode with `next dev --turbo`) works with CometChat. No special configuration needed. If you encounter issues, fall back to the standard Webpack dev server (`next dev` without `--turbo`).
-
-### Pages Router: do NOT use CometChat from `getServerSideProps` / `getStaticProps` / `getInitialProps`
-
-**Symptom:** `ReferenceError: window is not defined` or cryptic SDK errors during `next build` or page rendering.
-
-**Cause:** The CometChat client SDK needs the browser (localStorage, WebSocket, etc.) and a logged-in user session. It cannot run inside `getServerSideProps`, `getStaticProps`, or `getInitialProps` — those execute on the Node.js server before the browser has hydrated.
-
-**Fix:** Do chat-related work in client components only. If you need to pre-seed a conversation from server data, pass just the primitive IDs (user UID, group GUID) as page props and let the client component fetch the CometChat entity on mount:
-
-```tsx
-// pages/products/[id].tsx — server-side data fetch, no CometChat
-export async function getServerSideProps({ params }) {
-  const product = await fetchProduct(params.id);
-  return { props: { product } }; // pass sellerId as string, not a CometChat.User
-}
-
-export default function ProductPage({ product }) {
-  return (
-    <>
-      <h1>{product.name}</h1>
-      <ChatWithSeller sellerUid={product.sellerId} /> {/* client component */}
-    </>
-  );
-}
-```
-
-### Pages Router: `_document.tsx` doesn't need CometChat changes
-
-If the project has a custom `pages/_document.tsx` for font preloading or third-party SSR CSS injection, leave it alone. CometChat CSS variables are client-side only — they don't need `_document.tsx` integration. Mount the CSS import in `_app.tsx` as shown in section 10; `_document.tsx` is the wrong layer.
-
----
-
-## 12. Complete integration checklist (App Router)
-
-1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
-2. Create `.env.local` with `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY`
-3. Import `@cometchat/chat-uikit-react/css-variables.css` in `app/globals.css`
-4. Create `app/providers/CometChatProvider.tsx` with `"use client"` (section 3)
-5. Mount `CometChatProvider` in `app/layout.tsx` wrapping `{children}`
-6. Create `app/messages/page.tsx` with `"use client"` (section 5)
-7. Add a `<Link href="/messages">Messages</Link>` to the layout's nav
-8. Verify: `npm run build` should succeed without SSR errors
-
-## 13. Complete integration checklist (Pages Router)
-
-1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
-2. Create `.env.local` with `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY`
-3. Import `@cometchat/chat-uikit-react/css-variables.css` in `pages/_app.tsx`
-4. Create `components/CometChatProvider.tsx` (section 3 code, without `"use client"`)
-5. Dynamically import `CometChatProvider` in `pages/_app.tsx` with `ssr: false` (section 4)
-6. Create `pages/messages.tsx` with dynamic import (section 6)
-7. Add a `<Link href="/messages">Messages</Link>` to the layout's nav
-8. Verify: `npm run build` should succeed without SSR errors
-
-## 14. Visual Builder integration (v4.3)
-
-If the customer picks **Visually** in dispatcher Step 3.1, the Next.js recipe diverges based on App Router vs Pages Router. Skills runs `cometchat builder export --platform react --output <target>` to download the canonical `src/CometChat/` + patch settings in one step.
-
-**Full recipe lives in `cometchat-core` §11 "Visual Builder integration".** This section is a pointer + Next.js-specific gotchas:
-
-### App Router (recommended for Visual Builder)
-
-- Run `cometchat builder export --platform react --output src/app/CometChat --json`.
-- Create `src/app/CometChatNoSSR/CometChatNoSSR.tsx` (client component, init + login + render).
-- Create `src/app/CometChatAppWrapper.tsx` with `"use client"` + `dynamic(() => import("../app/CometChatNoSSR/CometChatNoSSR"), { ssr: false })`.
-- Import the wrapper in `src/app/page.tsx`.
-- **Patch `src/app/CometChat/context/CometChatContext.tsx`** to use `'../../../../package.json'` (4 levels up) instead of canonical's `'../../../package.json'` (3 levels). **Finding F16** — depth differs because the directory moved into `src/app/`.
-
-### Pages Router (NOT recommended)
-
-**Finding F17** (2026-05-22): Next.js Pages Router enforces "global CSS imports only in `pages/_app.tsx`". The canonical `src/CometChat/` has 25+ component-level CSS imports — Pages Router rejects the build. App Router tolerates this; Pages Router does not. Recommend App Router instead.
-
-If a customer insists on Pages Router + Visual Builder, the only workaround is to convert all 25+ canonical CSS files into CSS Modules — heavy customer-side work. Not validated in v4.3.0.
-
-### Both routers
-
-- Use `process.env.NEXT_PUBLIC_COMETCHAT_*` (NOT `import.meta.env.*` which is Vite-only).
-- Pin `@cometchat/chat-uikit-react@6.4.3` + `@cometchat/calls-sdk-javascript@4.2.5`.
-- `package.json` needs `cometChatCustomConfig` block (Finding F2).
-
-If the customer picks **In code**, ignore this section.