buddi-chat-widget

React chat widget library with SSR-safe entry points for Next.js App Router and other modern bundlers.

Compatibility Matrix

| Area | Baseline / Supported | | --- | --- | | React runtime | >=18.3.1 <20 | | React DOM runtime | >=18.3.1 <20 | | Next.js test baseline | 15.0.7 | | Bundlers tested | Turbopack, Webpack, Vite | | Module formats | ESM + CJS |

Installation

npm install buddi-chat-widget

Package Exports

• buddi-chat-widget:
  • import -> ESM runtime entry
  • require -> CJS runtime entry
  • types -> declaration entry
  • react-server -> server-safe placeholders
• buddi-chat-widget/styles.css -> compiled distributable stylesheet
• buddi-chat-widget/client -> explicit client-only entry (use client)
• buddi-chat-widget/server -> explicit server-safe entry

Next 15 App Router Example

'use client';

import 'buddi-chat-widget/styles.css';
import { ChatWidget, FeatureFlagProvider } from 'buddi-chat-widget/client';

export default function SupportWidget() {
  return (
    <FeatureFlagProvider
      flags={{
        enableMessengerMode: true,
        enableClassicChat: true,
      }}
    >
      <ChatWidget />
    </FeatureFlagProvider>
  );
}

Vite Example

import React from 'react';
import ReactDOM from 'react-dom/client';
import 'buddi-chat-widget/styles.css';
import { ChatWidget, FeatureFlagProvider } from 'buddi-chat-widget/client';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <FeatureFlagProvider>
    <ChatWidget />
  </FeatureFlagProvider>
);

SSR-Safe Import Example

import { ChatWidget } from 'buddi-chat-widget/server';

// Safe on server: this placeholder renders null.
export function ServerPreview() {
  return ChatWidget();
}

Styling and Theming

Import the packaged CSS once:

import 'buddi-chat-widget/styles.css';

The widget is scoped under .bdw-chat-widget to reduce host-style collisions and does not ship global html/body/* resets.

Theme Tokens (defaults)

Color tokens:

• --color-brand: #EC4C32
• --color-text-primary: #1B2025
• --color-surface-default: #F7F9FC
• --color-border-primary: #EAEEF2

Radius tokens:

• --bdw-radius-sm: 8px
• --bdw-radius-md: 12px
• --bdw-radius-lg: 16px

Spacing tokens:

• --bdw-space-1: 4px
• --bdw-space-2: 8px
• --bdw-space-3: 12px
• --bdw-space-4: 16px

Shadow tokens:

• --bdw-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08)
• --bdw-shadow-md: 0 6px 16px rgba(0, 0, 0, 0.12)

Font tokens:

• --bdw-font-family: 'Manrope', sans-serif

Override tokens in your app CSS:

.bdw-chat-widget {
  --color-brand: #0c51af;
  --bdw-radius-lg: 20px;
}

Optional maximum isolation strategy: render your host wrapper in Shadow DOM and inject buddi-chat-widget/styles.css inside that shadow root.

Accessibility Baseline

• Keyboard interactive controls use native button semantics.
• Dialog controls include close actions and keyboard focusable elements.
• Live message updates are rendered in readable DOM order for screen readers.
• Ensure host theme overrides maintain WCAG AA contrast.

Security Baseline

• Avoid dangerouslySetInnerHTML by default.
• Validate URLs before rendering user-provided links.
• Do not expose auth tokens in client logs.

Troubleshooting

document is not defined

Use buddi-chat-widget/client in client components only, or import from buddi-chat-widget/server for server-rendered placeholders.

CSS not applied

Ensure import 'buddi-chat-widget/styles.css'; runs once in your client bundle.

Next.js RSC boundary warning

Keep chat widget usage in files with 'use client'; or use dynamic client-side loading.

Release Notes

See RELEASE_NOTES.md for published compatibility and packaging changes.