dev-tools 5 min read

Cossistant – AI Support Widget for React Apps

Open-source AI support widget for React and Next.js with headless components, real-time messaging, and code-first customization for developers.

#ai-setup #dev-tools #react #open-source
By
Share: X in
Cossistant product thumbnail

TL;DR

TL;DR: Cossistant is an open-source AI support widget for the React ecosystem that treats customer chat as a code-defined, composable layer — letting you embed, customize, and even hand off conversations to AI agents without vendor lock-in.

Source and Accuracy Notes

⚠️ This section is MANDATORY. All links must be verified from actual source, not guessed.

What Is Cossistant?

Cossistant describes itself as “support defined in your code.” It is an open-source chat and AI support widget for React and Next.js apps, built with a code-first philosophy that treats customer support as a composable, programmable part of the stack rather than a third-party SaaS integration.

The core pitch from the HN launch:

“I want the support in my SaaS to feel like my product: fully customizable, part of the UI, and able to access my codebase so AI agents can actually do useful things.”

The project ships headless React components, a real-time messaging backend, and complete infrastructure via Docker (Postgres + Redis). It is not a hosted SaaS — you deploy your own.

Setup Workflow

Step 1: Install the React SDK

npm install @cossistant/react

Or with pnpm:

pnpm add @cossistant/react

Step 2: Add the widget to your app

For Next.js apps, a dedicated @cossistant/next package provides bindings:

npm install @cossistant/next

Then wrap your app layout with the provider:

// app/layout.tsx (Next.js App Router)
import { CossistantProvider } from '@cossistant/next'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CossistantProvider />
        {children}
      </body>
    </html>
  )
}

For plain React (Vite, CRA, etc.), use the core @cossistant/react package directly.

Step 3: Place the widget component

Drop the <Support /> component anywhere in your component tree:

import { Support } from '@cossistant/react'

export function HelpButton() {
  return <Support trigger="Chat with us" />
}

Step 4: Configure via environment variables

Cossistant uses standard env vars for API keys and backend URL. Refer to the keys docs for the full list.

Deeper Analysis

Architecture

Cossistant is a monorepo built with Turborepo, Bun, and TypeScript. The stack on the frontend is React + Next.js; the backend uses Hono (API layer), tRPC (type-safe RPC), and Drizzle ORM connecting to Postgres. Real-time messaging goes over WebSockets.

Key packages:

| Package | Purpose | |---|---| | @cossistant/react | Headless React hooks and primitives | | @cossistant/next | Next.js-specific bindings and utilities |

What makes it different from Intercom or Crisp?

Most embedded support widgets are closed-source SaaS with pricing tiers that scale per seat or conversation. Cossistant is self-hostable, AGPL-3.0, and designed as a developer tool first — the widget is a React component you render, not a script embed you paste from a dashboard.

The “AI agents can understand your codebase” framing is the distinctive angle: instead of training a bot on scraped docs, you expose your internal context directly to the AI through code-defined support flows.

Real-time and state management

The widget manages its own conversation state and connects to the backend via WebSockets for live messaging. This means conversations survive page reloads and can be synced across tabs.

Practical Evaluation Checklist

  • [ ] npm package installs without peer dep warnings
  • [ ] Widget renders in a Next.js App Router layout without hydration errors
  • [ ] WebSocket connects to the backend within 2 seconds
  • [ ] Typing the same query twice produces different AI responses (non-deterministic)
  • [ ] Support component accepts a trigger prop that overrides the default button label
  • [ ] Dark/light mode toggling works without re-mounting the widget
  • [ ] Docker compose brings up Postgres + Redis + API backend in one command
  • [ ] tRPC types are exported and usable in the host application

Security Notes

Cossistant runs as a self-hosted service, which means you control the data. Customer messages go to your own Postgres instance, not a third-party vendor. However:

  • The AGPL-3.0 license requires you to open-source modifications if you deploy a modified version
  • Commercial use requires a separate license agreement (contact [email protected])
  • WebSocket connections should be TLS-terminated in production — the default Docker compose does not include TLS
  • Review the Better Auth configuration before exposing the admin dashboard publicly

FAQ

Q: Is Cossistant completely free? A: For non-commercial open-source projects, yes — AGPL-3.0 covers that use case. For commercial SaaS deployments, a commercial license is required (contact [email protected] for pricing).

Q: Does it work without OpenAI? A: The widget can route conversations to any LLM with a compatible API (OpenAI-compatible). The specific AI behavior depends on how you wire up the routing in your codebase.

Q: Can I style the widget to match my brand? A: Yes — Cossistant explicitly markets headless components that expose styling primitives. You control the visual layer, not just the content.

Q: What is the deployment story? A: The project provides a Docker Compose setup (Postgres + Redis + API). Self-hosting is the primary deployment model; there is no managed cloud offering.

Conclusion

Cossistant is a developer-first take on embedded customer support — open-source, self-hostable, and built as composable React components rather than a generic SaaS widget. The AGPL-3.0 license and self-hosted model make it interesting for teams who want full data ownership and the ability to extend the support logic as code.

If you are building a React/Next.js SaaS and want to replace (or evaluate dropping) Intercom or Crisp, the quickstart guide is the fastest way to see if it fits your stack.

Related Posts

dev-tools

Automotive Skills Suite for AI Engineering

Evaluate Automotive Skills Suite for APQP, ASPICE, HARA, safety-plan, and DIA workflows with setup notes, governance risks, and SME review guidance.

5/28/2026

dev-tools

awesome-agentic-ai-zh Roadmap Guide

Explore awesome-agentic-ai-zh as a Chinese agentic AI learning roadmap, with setup notes, track selection, study workflow, and evaluation guidance.

5/28/2026

dev-tools

Baguette iOS Simulator Automation Guide

Set up Baguette for iOS Simulator automation, web dashboards, device farms, gesture input, streaming, and camera testing with Xcode caveats.

5/28/2026
Share this post: Share on X Share on LinkedIn