GVL Comments – React SDK

A production‑ready React + TypeScript comments system by GoodVibesLab.
Drop‑in UI, optimistic posting, moderation‑aware rendering, and a clean API — inspired by the Flutter SDK, designed for the web.

✨ Features

• ⚡ Instant comments UI (ready‑to‑use CommentsThread)
• 🧠 Optimistic posting (message appears instantly, confirmed by server)
• 🛡 Moderation‑aware rendering
  • Reported comments
  • Moderated (rejected) placeholders
• 🔁 Cursor‑based pagination (no offset bugs)
• 🎨 Customizable UI (render props, order, branding)
• 🧩 Provider‑based architecture (clean, scalable)
• 🟦 TypeScript first

📦 Installation

npm install @goodvibeslab/gvl-comments-react

or

yarn add @goodvibeslab/gvl-comments-react

🚀 Quick start

1️⃣ Wrap your app with CommentsProvider

import {
  CommentsProvider,
  CommentsThread,
} from "@goodvibeslab/gvl-comments-react";

<CommentsProvider
  config={{
    installKey: "cmt_live_xxx",
    externalUserId: "user_123",
    externalUserName: "John Doe",
    avatarUrl: "https://avatar.com/...",
    order: "newestBottom",
  }}
>
  <CommentsThread threadKey="post:123" />
</CommentsProvider>;

That’s it. You have a fully functional comments system.

🧠 Core concepts

CommentsProvider

The provider initializes the SDK and exposes:

• authenticated client
• current user
• plan & branding logic
• default thread configuration

interface CommentsProviderConfig {
  installKey: string;
  externalUserId: string;
  externalUserName?: string;
  avatarUrl?: string;
  order?: "newestTop" | "newestBottom";
}

Branding rules:

• free tenants → branding shown by default
• paid tenants → branding hidden
• showBranding always overrides

CommentsThread

High‑level, ready‑to‑use UI component.

<CommentsThread
  threadKey="post:123"
  order="newestBottom"
/>

Props:

• threadKey (required)
• order (newestBottom | newestTop)
• renderComment (advanced customization)

🎨 Custom rendering

You can fully override comment rendering:

<CommentsThread
  threadKey="post:123"
  renderComment={(comment, meta) => (
    <MyCustomBubble
      comment={comment}
      pending={meta.isPending}
      moderated={meta.isModerated}
    />
  )}
/>

Meta flags include:

• isMine
• isPending
• isReported
• isModerated

🛡 Moderation behavior

The SDK automatically handles:

• Reported comments → soft‑hidden placeholder
• Rejected comments → hard moderation message
• Pending comments → reduced opacity (optimistic state)

You don’t need to implement this logic yourself.

📚 Advanced usage

Low‑level client (optional)

If you don’t want the UI:

import { CommentsClient } from "@goodvibeslab/gvl-comments-react";

const client = new CommentsClient({
  installKey: "cmt_live_xxx",
});

Useful for headless or custom UIs.

🧪 Demo

A hosted demo is available soon on https://goodvibeslab.cloud/app/demo/comments/react

npm run dev

🛣 Roadmap

Upcoming features:

• 📸 Image attachments (upload, moderation, thumbnails)
• ❤️ Reactions (👍 ❤️ 😂)
• 🔔 Realtime updates (WebSockets / Realtime)
• 🧑‍⚖️ Admin moderation tools

🧾 License

This SDK is proprietary software.

Usage of this package is subject to the GoodVibesLab Terms of Service. You may not copy, modify, redistribute, or resell this software without explicit authorization.

© GoodVibesLab. All rights reserved.

💬 Support

Questions, issues, or enterprise needs?
→ contact GoodVibesLab or open a GitHub issue.