@entroparc/entrofeed-widget

Embeddable React feedback widget for Entrofeed.

For the simplest install, use the hosted script from the Entrofeed project page. Use this React package when the host app needs typed props, richer user context, explicit theme tokens, or custom submit callbacks.

Install

npm install @entroparc/entrofeed-widget
# or
pnpm add @entroparc/entrofeed-widget

Usage

"use client";

import { usePathname } from "next/navigation";
import { EntrofeedWidget } from "@entroparc/entrofeed-widget";

export function ProductFeedback({ user }: { user: { id: string; email?: string } }) {
  const pathname = usePathname();

  return (
    <EntrofeedWidget
      apiBaseUrl={process.env.NEXT_PUBLIC_ENTROFEED_URL!}
      projectKey={process.env.NEXT_PUBLIC_ENTROFEED_PROJECT_KEY!}
      user={{ id: user.id, label: user.email }}
      context={{ path: pathname, route: pathname }}
    />
  );
}

Mount the component once in the host app shell or product layout.

AI Agent Install Prompt

Use this prompt inside a host app repo:

Install Entrofeed feedback into this React/Next.js app.

Use the repo's package manager to add @entroparc/entrofeed-widget.
Set NEXT_PUBLIC_ENTROFEED_URL and NEXT_PUBLIC_ENTROFEED_PROJECT_KEY in the host
app environment.
Mount EntrofeedWidget once in the authenticated app layout or product shell.
Pass the current pathname as both path and route, and pass the current user
id/email when available.
Do not put server secrets in NEXT_PUBLIC vars.
Run lint/build after the change, then submit one live test feedback item and
confirm it appears in Entrofeed.

Required Environment

NEXT_PUBLIC_ENTROFEED_URL=https://www.entrofeed.com
NEXT_PUBLIC_ENTROFEED_PROJECT_KEY=pk_live_xxx

The project key identifies the Entrofeed project. It is not a secret, but it should still be bound to the exact origins that are allowed to submit feedback. The widget also sends the public project key in the submit URL so Entrofeed can answer CORS preflight requests using the project-key origin bindings. Use the canonical Entrofeed app URL. Browser CORS preflights cannot follow domain redirects, so do not use an apex URL if it redirects to www.

Updating An Existing Host App

If the host app already has an older local widget copy, remove that local widget or local package reference, install @entroparc/entrofeed-widget, and replace imports with:

import { EntrofeedWidget } from "@entroparc/entrofeed-widget";

Props

| Prop | Type | Required | Notes | | --- | --- | --- | --- | | apiBaseUrl | string | Yes | Entrofeed app URL. Empty string falls back to the current browser origin, useful for same-origin previews. | | projectKey | string | Yes | Public project key from Entrofeed. | | triggerLabel | string | No | Accessible label and tooltip for the launcher. | | title | string | No | Panel title. | | description | string | No | Short helper copy below the title. | | feedbackTypes | { id: string; label: string }[] | No | Category pills shown above the message field. | | user | { id?: string; label?: string } | No | Current user identity from the host app. | | context | { path?: string; route?: string; appVersion?: string; feedbackType?: string } | No | Host-app context. Current browser path is added automatically and can be overridden. | | placement | "bottom-right" \| "bottom-left" | No | Launcher position. | | requestTimeoutMs | number | No | Submit timeout. Defaults to 12000. | | attachmentUploadTimeoutMs | number | No | Attachment upload timeout when file capture is enabled. Defaults to 60000. | | captureFeatures | ("files")[] | No | Opt-in richer capture features. Omit this prop to keep the default simple widget. | | onSubmitted | (feedbackEventId: string) => void | No | Called after a successful submit. | | onError | (error: Error) => void | No | Called after a failed submit. | | theme | EntrofeedWidgetTheme | No | Explicit, sanitized theme token overrides for brand fit. |

Optional File Attachments

Manual file attachment capture is opt-in. Enable it only for design-partner or internal review flows where the user intentionally chooses a screenshot or document:

<EntrofeedWidget
  apiBaseUrl={process.env.NEXT_PUBLIC_ENTROFEED_URL!}
  projectKey={process.env.NEXT_PUBLIC_ENTROFEED_PROJECT_KEY!}
  captureFeatures={["files"]}
/>

The widget submits feedback first, then requests a short-lived private upload token for the chosen file. Attachments are stored privately in Entrofeed and are downloaded through authenticated Entrofeed routes by operators.

Default installs do not show file controls.

Theming

The widget keeps the Entrofeed design by default. Host apps can pass explicit theme tokens when they want the launcher and panel to sit closer to the product brand:

import {
  EntrofeedWidget,
  type EntrofeedWidgetTheme,
} from "@entroparc/entrofeed-widget";

const theme: EntrofeedWidgetTheme = {
  accent: "#c49349",
  accentForeground: "#17120a",
  background: "#211d1a",
  panel: "#26221e",
  panelElevated: "rgba(18, 16, 14, 0.9)",
  border: "rgba(255, 255, 255, 0.07)",
  foreground: "#d4d1ca",
  muted: "#8b857d",
  radius: 12,
};

export function ProductFeedback() {
  return (
    <EntrofeedWidget
      apiBaseUrl={process.env.NEXT_PUBLIC_ENTROFEED_URL!}
      projectKey={process.env.NEXT_PUBLIC_ENTROFEED_PROJECT_KEY!}
      theme={theme}
    />
  );
}

Supported theme tokens:

| Token | Purpose | | --- | --- | | accent | Primary action and active signal color. | | accentForeground | Text color on top of the accent color. | | background | Launcher and outer panel surface. | | panel | Inner panel surface. | | panelElevated | Message field surface. | | border | Subtle border color used by controls. | | foreground | Primary text and icon color. | | muted | Secondary text color. | | radius | Outer panel radius, clamped from 4 to 24 pixels. |

Theme values are intentionally bounded. The widget accepts normal CSS color strings such as hex, rgb/rgba, hsl/hsla, named colors, and CSS variables, but it drops suspicious values such as url(...), expression(...), HTML-like text, or long raw CSS fragments. radius accepts a number or a pixel string from 4px to 24px.

Automatic host-site theme detection is not enabled. A future auto mode should be explicitly opt-in, deterministic, and lower priority than the theme prop.

Behavior

• Sends POST /api/widget/submit?projectKey=... to Entrofeed.
• When captureFeatures={["files"]} is enabled, sends POST /api/widget/attachments/upload-token?projectKey=... after feedback creation, then uploads the selected file with a private Vercel Blob client token.
• Adds the current browser path and route by default.
• Omits browser credentials from the request.
• Shows visible success and error states.
• Times out stalled requests after requestTimeoutMs.
• Keeps React and React DOM as peer dependencies.

Release

Releases are intended to be published from GitHub Actions using npm trusted publishing and provenance. Create a Git tag like:

git tag widget-v0.1.0
git push origin widget-v0.1.0

Before tagging, update package.json, CHANGELOG.md, and run:

npm run widget:build
npm --prefix packages/entrofeed-widget run pack:dry