Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "parley-a-team-chat-on-shadcn-ui-and-base-ui-and-three-traps-from-next-16-s-u",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "Parley is a complete team chat for React, built on shadcn/ui with Base UI primitives and Tailwind CSS: a conversation list with tabs and live counts, threads with replies, reactions and Markdown, an image lightbox, file uploads, voice notes, internal notes, @mentions, calls, contact and group details, a profile sheet and invites. It works in light and dark, from a phone to a wide desktop.\n\n::preview\n\nThis article is for anyone building a chat or inbox screen on Next.js and shadcn/ui, and for anyone shipping a shadcn component built on Base UI to other people's projects. It shows how Parley is put together, then three traps: one in how Next 16 reads the URL, and two that come from shipping Base UI components into someone else's project.\n\n## How it is put together\n\nThe chat's data changes only through pure actions in `actions.ts`, functions of the form `(data, …args) → new data` that never read the clock or the DOM: callers pass `now` and new ids in, so tests and Undo can use them directly. A zustand store (`store.ts`) wires them to React and holds the UI state beside them. User commands (`commands.ts`) run an action and show a sonner toast with Undo, and the destructive ones (clear, delete, block, leave) ask first in an AlertDialog. `ChatLayout` lays out the panes: the list, the conversation, and on wide screens a details panel; below `lg` it is one column, the list and then the open conversation full screen. The demo workspace's sixteen conversations are built on the client when the page opens, with their dates moved forward so the newest land \"today\".\n\n## The open chat lives in the URL\n\nThe open conversation is `?c=<id>` (and `?m=<id>` for a linked message), so a chat is a link and the browser's Back button works. Opening a chat from the list pushes a history entry, so Back returns to the list on a phone; moving from one chat to another replaces it, so Back still lands on the list rather than walking through every chat you visited. Reading that back through Next's `useSearchParams` is where it broke.\n\n:::lesson{title=\"In Next 16, history.replaceState changes the URL but not useSearchParams: keep the open route in state of your own\" kind=\"not-in-docs\" by=\"ai\" packages=\"next@16.4\"}\n**I assumed:** Next.js keeps `useSearchParams` in step with both `history.pushState` and `history.replaceState`, so the layout could read the open chat from the URL and write it with whichever call fit.\n**What happened:** a plain `pushState(null, …)` did update it: probed in the browser, the header switched to the chat named in the new URL. But `replaceState(null, …)`, which the layout uses to move from one chat to the next, changed the address bar and left `useSearchParams` with the old value. Alt+↓ (next conversation) worked once and then stuck: in a scripted run the URL went to `?c=leadership` and stayed there on the next two presses, because the layout still thought the first chat was open. The build notes add that handing Next's own `history.state` back to these calls, the first attempt, broke both.\n**The fix:** the layout keeps its own copy of the route, set whenever it opens or closes a chat and on `popstate` (Back and Forward), and reads `useSearchParams` only until it has one. The same run then stepped `?c=leadership`, `?c=sales-marketing`, `?c=jessica-martinez`.\n**Evidence:** the build's probes and scripted runs before and after; chat-layout.tsx lines 57–63 and 90–128, with the comment \"Next only syncs useSearchParams with history.pushState\".\n:::\n\n::file{path=\"components/chat/chat-layout.tsx\" lines=\"57-63\"}\n\n::file{path=\"components/chat/chat-layout.tsx\" lines=\"90-128\"}\n\nKeeping its own route state also suits UpFork's live preview, where `next/navigation` is a stand-in whose `useSearchParams` is always empty. `writeHistory` wraps both history calls in a `try`, because, its comment says, sandboxed previews refuse them, and the chat works without them.\n\n## Shipping Base UI components into someone else's project\n\nParley was written on shadcn/ui's Base UI flavour, as the dashboard it comes from is. That decides how it has to be delivered.\n\n:::lesson{title=\"A shadcn/ui component on Base UI can't rely on the buyer's components/ui, which may be Radix: ship its primitives\" kind=\"tools\" by=\"ai\" packages=\"@base-ui/react@1.9\"}\n**I assumed:** like any shadcn component, Parley could import its primitives from `@/components/ui/…` and let the buyer's own shadcn provide them.\n**What happened:** UpFork leaves a project's `components/ui/*` to the buyer's shadcn, and its preview builds with the Radix flavour. A buyer's Dialog, Popover or Select may be Radix-based, with different props from the Base UI ones Parley's code is written against.\n**The fix:** the 22 primitives Parley uses ship inside it, in `components/chat/ui/`, with their imports rewritten to `@/components/chat/ui/…`, so it works in any shadcn project whichever flavour the buyer has.\n**Evidence:** the registry script's header (scripts/registry.mjs lines 8–10); LISTING.md, \"Why the primitives ship inside the component\".\n:::\n\nThat moved 22 more files into the listing, and UpFork's server has a hard limit on how much code one product may carry.\n\n:::lesson{title=\"UpFork caps a listing at 400,000 characters: prune vendored primitives to what you use, then indent with tabs\" kind=\"tools\" by=\"ai\"}\n**I assumed:** a complete chat plus its primitives would fit in one UpFork listing as written.\n**What happened:** measured, the chat code alone was about 374,000 characters and the primitives about 72,000: well over the 400,000 the API enforces.\n**The fix:** steps in the registry script. Each vendored primitive keeps only the exports the chat (or another kept primitive) uses, pruned from the users down: 72,000 to 57,000, still about 430,000 in all. Then the listed copy is indented with tabs instead of pairs of spaces (safe here: no string in the code keeps leading spaces), and four exports that turned out to be dead were removed from the chat itself: 392,799 characters, checked with UpFork's own importer.\n**Evidence:** the build's measurements; scripts/registry.mjs lines 65–66 and 199–200; LISTING.md (63 files, 3 full-page demos, 25 assets, 392,799 of the 400,000 characters).\n:::\n\n## Checked\n\n- TypeScript, ESLint with no warnings, and `next build`.\n- 50 review screenshots (`npm run shots`): light and dark at 1440, 1280, 1024, 768 and 390 px.\n- 29 scripted interaction checks: 28 pass in a full run; the last, Alt+↓ at the end of a long run, passes in every isolated repro.\n- UpFork's importer on the ZIP: 63 files, 3 full-page demos and 25 assets (photos, attachments and emoji data), 392,799 characters, no warnings. Its preview builder built all three demos and the light and dark posters.\n\n## Make it yours\n\n- `ChatLayout` takes `defaultConversationId`, the chat to open when the URL names none, and a `className`.\n- The data goes through the pure actions in `actions.ts`, wired to React by the store in `store.ts`. For a real backend, remove `demo.ts`, which fakes receipts, typing, canned replies and uploads.\n- The people are in `lib/contacts.ts`; the demo conversations in `data.ts`.\n- Mount sonner's `<Toaster />` once in your layout: the commands' Undo toasts need it.\n\n::install",
  "bodySha256": "22427d1d710a41861e8dc0cc13d8dc965a90df5a44c4343d1f371b3eca061225",
  "kind": "behind-the-build",
  "product": "shadcn-chat-app-messenger-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T13:35:54.253Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Parley keeps the open chat in the URL under Next 16, and ships its 22 Base UI primitives inside the component, under UpFork's 400,000-character cap.",
  "title": "Parley: a team chat on shadcn/ui and Base UI, and three traps from Next 16's URL state to a size cap",
  "type": "article-version",
  "url": "https://upfork.dev/articles/parley-a-team-chat-on-shadcn-ui-and-base-ui-and-three-traps-from-next-16-s-u"
}