Customer Instant Feedback App

A React component library for collecting user feedback directly within your application. Uses a centralized Supabase backend with reviewer-based authentication.

Features

• Capture screenshots with feedback
• Annotate specific elements
• Categorize feedback (Bug, UX, Content, Other)
• Reviewer-based authentication (no anonymous feedback)
• Admin UI for managing companies, projects, and reviewers
• Feedback review page for reviewers to see all feedback (including from colleagues)
• Client-side rate limiting
• Input validation

Installation

In your React project:

npm install @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom

Or with yarn:

yarn add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom

Or with pnpm:

pnpm add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom

Note: React, React DOM, React Router, and Supabase are peer dependencies. If your project already has them, you only need to install the feedback package.

Quick Start

1. Environment variables (host project)

Add these to your host project's .env file (not this package):

Vite / Create React App:

VITE_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
VITE_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key

Next.js:

NEXT_PUBLIC_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key

Get these from Supabase: Project Settings → API. Use the anon (public) key.

TypeScript users: Add type definitions for these environment variables. For Vite projects, create src/vite-env.d.ts:

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_FEEDBACK_SUPABASE_URL: string
  readonly VITE_FEEDBACK_SUPABASE_ANON_KEY: string
}

For Next.js, add to next-env.d.ts or create a similar declaration file.

Alternatively, call configureFeedbackClient({ url, anonKey }) at app init.

2. Database migrations

Run these SQL files in your Supabase SQL editor, in order:

1. migrations/schema_central.sql – Creates tables
2. migrations/extend_feedback_items.sql – Skip for new installs. Only run if you already have feedback_items from a previous setup; running on a fresh install will fail.
3. migrations/rls_central.sql – RLS policies
4. migrations/create_admin.sql – Creates your first admin (replace placeholder UUID)

3. Edge Functions (required for admin)

The admin UI uses Edge Functions to create/delete reviewers. Deploy them:

# From the package root (e.g. node_modules/@rensblitz/customer-instant-feedback-app)
supabase functions deploy create-reviewer
supabase functions deploy delete-reviewer

Or copy supabase/functions/ into your Supabase project and deploy.

4. Wrap your app

In your root component (e.g. App.tsx or main.tsx):

import {
  FeedbackAuthProvider,
  FeedbackProvider,
  FeedbackLoginPage,
  FeedbackAdminPage,
  FeedbackReviewPage,
} from '@rensblitz/customer-instant-feedback-app';
import '@rensblitz/customer-instant-feedback-app/style.css';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

const projectId = 'your-project-id';

function App() {
  return (
    <FeedbackAuthProvider>
      <BrowserRouter>
        <Routes>
          <Route path="/feedback-login" element={<FeedbackLoginPage />} />
          <Route path="/feedback-admin" element={<FeedbackAdminPage />} />
          <Route path="/feedback" element={<FeedbackReviewPage projectId={projectId} />} />
          <Route
            path="/*"
            element={
              <FeedbackProvider projectId={projectId} feedbackReviewPath="/feedback">
                <YourApp />
              </FeedbackProvider>
            }
          />
        </Routes>
      </BrowserRouter>
    </FeedbackAuthProvider>
  );
}

Important: Always import the CSS file. Without it, the feedback modal has no styles.

5. Get your project ID

Go to /feedback-admin, create a company and project, then copy the project_id (format: short-code_uuid) and pass it to FeedbackProvider and FeedbackReviewPage.

6. Create the first admin

1. Create a user in Supabase: Authentication → Users → Add user (email + password)
2. Copy the user's UUID
3. Run the SQL from migrations/create_admin.sql (replace the placeholder UUID)

How it works

• Reviewers visit /feedback-login to sign in with credentials provided by an admin. Only logged-in reviewers can see and use the feedback widget. They can visit /feedback to see all feedback for the project (including from colleagues).
• Admins visit /feedback-admin to manage companies, projects, and reviewers. Only users in the admins table can access this page.
• Feedback is stored in the centralized Supabase project, scoped by project. Each host app passes its projectId to identify which project the feedback belongs to.

Usage

FeedbackProvider props

<FeedbackProvider
  projectId="acme-dash_abc123-uuid"  // Required for full functionality
  enabled={true}
  rateLimitSeconds={30}
  validation={{
    maxCommentLength: 2000,
    maxNameLength: 100,
    maxScreenshotSize: 500000,
  }}
>
  <YourApp />
</FeedbackProvider>

• projectId: The project identifier from the admin UI. If omitted, a warning banner is shown.
• enabled: Toggle the feedback feature on/off.
• feedbackReviewPath: Path to the feedback review page (default: /feedback). Used for the "View all" link in the feedback toolbar.
• rateLimitSeconds: Minimum seconds between submissions.
• validation: Input validation limits.

Rate limiting

<FeedbackProvider projectId="..." rateLimitSeconds={60}>
  <YourApp />
</FeedbackProvider>

Validation

<FeedbackProvider
  projectId="..."
  validation={{
    maxCommentLength: 500,
    maxNameLength: 50,
    allowScreenshots: true,
    maxScreenshotSize: 1024 * 1024,
  }}
>
  <YourApp />
</FeedbackProvider>

Migrations (central Supabase project)

Run these migrations in your Supabase SQL editor, in order:

1. migrations/schema_central.sql – Creates companies, projects, admins, reviewers, and feedback_items tables
2. migrations/extend_feedback_items.sql – Skip for new installs. Only run if you are upgrading an existing installation that already has a feedback_items table from a prior setup. Running on a fresh install will fail.
3. migrations/rls_central.sql – RLS policies
4. migrations/create_admin.sql – Template for creating first admin(s)

TypeScript types

interface ValidationConfig {
  maxCommentLength?: number;
  maxNameLength?: number;
  allowScreenshots?: boolean;
  maxScreenshotSize?: number;
}

interface FeedbackProviderProps {
  children: React.ReactNode;
  projectId?: string;
  enabled?: boolean;
  rateLimitSeconds?: number;
  validation?: ValidationConfig;
  feedbackReviewPath?: string;
}

interface FeedbackReviewPageProps {
  projectId: string;
}

Development

Testing the library locally

The demo/ folder contains a separate app that imports the library like a real consumer would:

1. First time setup:

   npm run demo:install
   npm link
   cd demo && npm link @rensblitz/customer-instant-feedback-app

   Add VITE_FEEDBACK_SUPABASE_URL and VITE_FEEDBACK_SUPABASE_ANON_KEY to demo/.env (copy from demo/.env.example if present).

2. Build the library:

   npm run build

3. Run the demo app:

   npm run demo

The demo app imports from node_modules using npm link, so it works exactly like a real host app.

After making changes to the library:

• Rebuild: npm run build
• The demo will hot-reload automatically

Demo includes:

• /feedback-admin - Admin interface for managing companies, projects, and reviewers
• /feedback-login - Login page for reviewers
• /feedback - Feedback review page
• /readme - Setup guide (also available as FeedbackReadmePage for host apps)
• / - Demo page with the feedback widget

Building for npm

npm run build

Builds the library (ESM, CommonJS, TypeScript declarations, CSS).

Publishing to npm

npm publish --access public

The package is configured for npm distribution with proper exports.

License

MIT © Rens Blitz