Package Reference
Troubleshooting
Overview
Most integration issues fall into a few buckets: Tailwind scanning, credentials (especially JWT _id), viewport height, and framework bundler config. Use the table below for a quick lookup, then read the deep dives for the highest-impact fixes.
Related guides: Project Setup, FAQ, and Customization.
Common problems
| Problem | Cause | Fix |
|---|---|---|
| Unstyled / broken UI | Missing Tailwind @source entries | Add @source pointing at dist/index.mjs and dist/index.cjs |
| No styles at all | Missing styles.css import | @import "@realtimexsco/live-chat/styles.css" |
| Wrong @source depth | Next.js vs Vite path difference | Use ../../node_modules in src/app/globals.css |
| TypeScript: no declaration file | Published tarball missing dist/index.d.ts | Reinstall the latest version; verify dist/index.d.ts exists |
| Next.js build error | Package not transpiled | transpilePackages: ["@realtimexsco/live-chat"] |
| "use client" error | Server Component import | Add "use client" to the chat page |
| Whole page scrolls, not just messages | Missing height chain | Set viewportHeight="screen" or "calc(100dvh - 4rem)" |
| Messages don't load | Wrong credentials / CORS | Check apiUrl, JWT, and dev proxy configuration |
| Socket won't connect | Wrong socketUrl | socketUrl must not include /api/v1 |
| Duplicate React hooks error | Duplicate React copies | dedupe: ["react", "react-dom"] in Vite config |
| Sent message shows on both left and right | _id mismatch or duplicate echo | Ensure loggedUserDetails._id matches the JWT _id |
| Custom layout has no data | Missing hook call | Call useChatController() inside your custom ChatLayout |
| Custom MembersDrawer still shows package UI | Package version older than 1.1.55 | Upgrade to 1.1.55 or later |
| Custom drawer works but other slots reverted to default | Expected behavior | Only slots you pass in components are overridden |
| Passed components but a slot is unchanged | Slot not wired, or a parent slot was replaced | Check the Components wired-slots table; replace ChannelHeader to override all header drawers |
| Custom HeaderCallActions crashes | Recursive import of the package's own HeaderCallActions | Render your own buttons instead of importing the package component |
| Vite shows stale UI after upgrade | Cached prebundle | rm -rf node_modules/.vite && pnpm dev |
| Rate limit banner appears | API returned HTTP 429 | Wait for the cooldown; reduce rapid API calls in development |
Unstyled or broken UI
Symptom: Chat renders as a bare list of text with no spacing, colors, or layout.
Check: Your global CSS imports Tailwind, the package stylesheet, and @source entries that point at the published dist files with the correct relative depth.
@import "tailwindcss";
@import "@realtimexsco/live-chat/styles.css";
/* Vite (src/index.css): */
@source "../node_modules/@realtimexsco/live-chat/dist/index.mjs";
@source "../node_modules/@realtimexsco/live-chat/dist/index.cjs";
/* Next.js (src/app/globals.css): use ../../node_modules/... */Copy the full token block from Project Setup so --chat-theme exists under :root.
JWT / _id mismatch
Symptom: Your sent messages appear on both sides of the thread, contacts look empty, or session sync fails.
Fix: Decode the JWT payload and set loggedUserDetails._id to the same _id (or id) claim. Prefer deriving it automatically:
function userIdFromToken(token: string): string | undefined {
try {
const payload = JSON.parse(
atob(token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/")),
);
return payload._id || payload.id;
} catch {
return undefined;
}
}Viewport height chain
Symptom: The whole page scrolls instead of only the message list, or the chat collapses to a short strip.
Fix: Give ChatMain an explicit height and ensure ancestors can shrink (min-h-0 / flex children). Use viewportHeight="screen" for a full-page chat, or a calc under a fixed app header:
<ChatMain
{...chatConfig}
viewportHeight="calc(100dvh - 4rem)"
/>Next.js transpilePackages
Symptom: Next.js fails to compile the package, or you see ESM / client-boundary errors when importing ChatMain.
Fix: Add the package to transpilePackages, mark the chat page with "use client", and use the PostCSS Tailwind plugin as shown in Project Setup.
const nextConfig = {
transpilePackages: ["@realtimexsco/live-chat"],
};
export default nextConfig;