Best Practices

These recommendations come from the most common integration issues we see when teams embed @realtimexsco/live-chat into React and Next.js apps. Follow them early to avoid silent message bugs, broken styling, and duplicate React instances.

For a step-by-step install checklist, see Support & Contact. For symptom-based fixes, use Troubleshooting.

• Keep secrets and connection values in chat.config.ts (or environment variables), and keep UI overrides in a separate customization module. That matches the production layout described in Package Structure.
• Always verify loggedUserDetails._idagainst the JWT payload before shipping. A mismatched id is the most common cause of "messages appear on the wrong side" bugs.
• Prefer environment variables for clientId, apiUrl, and socketUrl so the same config file works across local, staging, and production.

• Only pass the components and classNames keys you intend to override. Every omitted key falls back to the package default — never pass empty placeholder components for slots you want to keep.
• Use packageDefaultComponents to wrap and restyle a default component instead of rebuilding it from scratch. See Components and Customization.
• Never import a package component inside your own replacement for that same slot (for example, importing HeaderCallActions inside a custom HeaderCallActions). That creates infinite recursion.
• Pin the package to 1.1.56 or later if you customize drawers (MembersDrawer, ChannelDetailsDrawer, and related slots).

• Set an explicit height chain with viewportHeight or a wrapping h-dvh min-h-0 overflow-hidden container. Without it, the whole page scrolls instead of only the message list.
• Prefer viewportHeight="screen" for a full-page chat, or viewportHeight="calc(100dvh - 4rem)" under a fixed admin header. Details are in Quick Start.

• In Next.js, add "use client" on any file that imports the chat package, and include transpilePackages in next.config.ts.
• In Vite, add @realtimexsco/live-chat to optimizeDeps.exclude and dedupe React, Zustand, and Socket.IO to avoid duplicate-instance errors.
• Complete Tailwind v4 @source paths and --chat-theme* tokens as shown in Project Setup— missing CSS setup is the usual reason the UI looks unstyled.

• Use queryParamsByApi when different GET endpoints need different filter keys, instead of forcing one shared queryParams object. See API Integration.
• Remember that query-param props apply to REST only — they do not change the Socket.IO connection string. See Socket Events.