@magic-comment/widget

Embeddable visual feedback widget for web apps — reviewers click any element and leave threaded comments, synced in real time (Yjs/Hocuspocus). By Magic Team.

Install

pnpm add @magic-comment/widget

Usage

Script tag / CDN (no build step)

Drop one <script> on any page — no npm, no framework. The widget auto-mounts from data-* attributes and exposes window.MagicComment:

<script
  src="https://cdn.jsdelivr.net/npm/@magic-comment/widget/dist/magic-comment.global.js"
  data-project-id="my-project"
  data-server-url="wss://comments.example.com"
  data-api-key="pk_..."
  data-mode="preview"
></script>

The project review selected in the MagicComment dashboard is used by default. Pass data-review-id (or the framework reviewId prop) only as an explicit override.

Add data-auto-mount="false" to mount imperatively instead:

<script src=".../magic-comment.global.js" data-auto-mount="false"></script>
<script>
  MagicComment.mount({ projectId: "my-project", collaboration: { serverUrl, apiKey } });
</script>

A runnable example lives in examples/vanilla.

Vanilla (bundled)

import { mountMagicComment } from "@magic-comment/widget/embed";

mountMagicComment({
  projectId: "my-project",
  collaboration: { serverUrl: "wss://comments.example.com", apiKey: "pk_..." },
});

By default, the widget asks first-time reviewers for their display name when they first open the FAB. Pass promptForName: false only when you explicitly want anonymous guest names.

React

import { MagicCommentEmbed } from "@magic-comment/widget/react";

<MagicCommentEmbed projectId="my-project" collaboration={{ serverUrl, apiKey }} />;

Content-Security-Policy

The six built-in avatars, Magic Comment logo, and generic agent icon are bundled with the widget and render without image requests, so they do not need an img-src exception. Arbitrary external avatar URLs can still be blocked by the host page's policy; those degrade to a coloured initial.

connect-src 'self' wss://comments.example.com;

connect-src must list your collaboration server (data-server-url), and script-src the CDN you load the widget from.

Vue

<script setup>
import { MagicCommentEmbed } from "@magic-comment/widget/vue";
</script>

<template>
  <MagicCommentEmbed project-id="my-project" :collaboration="{ serverUrl, apiKey }" />
</template>