GVL Comments – React SDK

A production‑ready React + TypeScript comments system by GoodVibesLab.
Drop‑in UI, optimistic posting, moderation‑aware rendering, reactions support, 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
• ❤️ Reactions support (like 👍, ❤️, 😂)
• 🔒 Security first (install keys and user authentication)
• 🔁 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

import "@goodvibeslab/gvl-comments-react/styles.css";

This import is required to apply the default GVL Comments styles.

1️⃣ Wrap your app with CommentsProvider

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

<CommentsProvider
  config={{
    installKey: "cmt_live_xxx", // Your unique installation key for security
    externalUserId: "user_123",
    externalUserName: "John Doe",
    avatarUrl: "https://avatar.com/...",
    order: "newestBottom",
  }}
>
  <CommentsThread threadKey="post:3fa85f64-5717-4562-b3fc-2c963f66afa6" />
</CommentsProvider>;

That’s it. You have a fully functional comments system with reactions and secure access.

🧠 Core concepts

CommentsProvider

The provider initializes the SDK and exposes:

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

interface CommentsProviderConfig {
  installKey: string; // Unique key to secure your installation
  externalUserId: string; // User ID from your system
  externalUserName?: string;
  avatarUrl?: string;
  order?: "newestTop" | "newestBottom";
}

Branding rules:

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

Security model (web)

The installKey is intended to be used in the browser. Security is enforced by:

• allowed origins (app binding)
• short‑lived, scoped tokens
• rate limiting and abuse protection

You do not need to keep the install key secret in web applications.

CommentsThread

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

<CommentsThread
  threadKey="post:<uuid>" // Unique key for the comment thread
  order="newestBottom"
/>

Props:

• threadKey (required): uniquely identifies the comment thread (e.g., a blog post ID)
• order (newestBottom | newestTop)
• renderComment (advanced customization)

🎨 Custom rendering

You can fully override comment rendering:

<CommentsThread
  threadKey="post:<uuid>"
  renderComment={(comment, meta) => (
    <MyCustomBubble
      comment={comment}
      pending={meta.isPending}
      moderated={meta.isModerated}
      reactions={comment.reactions} // Access reactions data here
    />
  )}
/>

Meta flags include:

• isMine
• isPending
• isReported
• isModerated

❤️ Reactions support

Users can react to comments with emojis like 👍, ❤️, 😂. The SDK handles reactions optimistically and syncs with the server.

Reactions are available in the comment object and can be customized in rendering.

🛡 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.

🧵 Thread keys

Threads are identified by a deterministic string of your choice.

Recommended examples:

• post:3fa85f64-5717-4562-b3fc-2c963f66afa6
• article:01HV9ZJ7Q4X2M0YB8K9E

Guidelines:

• Use a stable identifier from your domain model
• Prefer high‑entropy IDs (UUID, ULID, Firestore docId, etc.)
• Avoid short or guessable values like post:1 or article:42

Thread keys are resolved automatically server‑side.

❓ Why GVL Comments (vs building it yourself)?

Building a production‑ready comments system usually requires:

• designing a database schema
• writing security rules and moderation logic
• handling pagination, abuse, and reactions
• maintaining backend infrastructure

GVL Comments provides all of this out of the box:

• moderation‑aware UI
• reactions support
• scoped authentication tokens
• hosted, tenant‑isolated backend
• zero backend code required

📚 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.

❓ FAQ

Q: How do I secure my comments system?
A: Use the installKey provided to you and configure allowed origins from the dashboard.

Q: Can I customize the UI?
A: Yes, via render props and theming options.

Q: Are reactions supported?
A: Yes, users can react to comments with emojis.

Q: How do I identify threads?
A: Use unique threadKey values per content item, like "post:123".

🧪 Demo

Run the local demo included in the repository:

npm run dev

🛣 Roadmap

Upcoming features:

• 📸 Image attachments (upload, moderation, thumbnails)
• 🔔 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.