@rensblitz/customer-instant-feedback-app 3.1.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +98 -231
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,79 +1,39 @@
1
- # Customer Instant Feedback App
1
+ # Feedback Module Setup
2
2
 
3
- A React component library for collecting user feedback directly within your application. Uses a centralized Supabase backend with reviewer-based authentication.
3
+ This project integrates the `@rensblitz/customer-instant-feedback-app` npm package to collect in-app feedback from reviewers. Feedback is stored in a **dedicated, separate Supabase project** — not in this project's own database.
4
4
 
5
- ## Repository layout (this monorepo)
5
+ ---
6
6
 
7
- - **`packages/customer-instant-feedback-app`** — the publishable npm package (`npm run build`, `npm publish -w @rensblitz/customer-instant-feedback-app`).
8
- - **`apps/demo`** — local consumer app (workspace `file:` link).
9
- - **`apps/demo-npm`** — same idea, but depends on the **published** package from npm (see `apps/demo-npm/README.md`).
10
- - **`apps/projectinablitz-frontend`** — operator web UI (deploy from repo root; see [`render.yaml`](./render.yaml)).
7
+ ## 1. Environment variables
11
8
 
12
- ## Production CI/CD
9
+ Add the following to `frontend/.env`:
13
10
 
14
- Pushes to **`main`** or **`master`**: migrations + Render hooks (see [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md)). PRs: build only.
11
+ ```env
12
+ # Feedback module — dedicated Supabase project
13
+ VITE_FEEDBACK_SUPABASE_URL=https://<your-supabase-project>.supabase.co
14
+ VITE_FEEDBACK_SUPABASE_ANON_KEY=<your-anon-key>
15
15
 
16
- ## Features
16
+ # The project ID assigned by projectinablitz (format: short-code_uuid)
17
+ VITE_FEEDBACK_PROJECT_ID=<your-project-id>
17
18
 
18
- - Capture screenshots with feedback
19
- - Annotate specific elements
20
- - Categorize feedback (Bug, UX, Content, Other)
21
- - Reviewer-based authentication (no anonymous feedback)
22
- - That operator UI is a **standalone app** in [`apps/projectinablitz-frontend/`](./apps/projectinablitz-frontend/) (not exported from the npm package in v3+)
23
- - Feedback review page for reviewers to see all feedback (including from colleagues)
24
- - Client-side rate limiting
25
- - Input validation
26
-
27
- ## Installation
28
-
29
- In your React project:
30
-
31
- ```bash
32
- npm install @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
19
+ # Set to "true" to enable the feedback widget, "false" to disable it
20
+ VITE_FEEDBACK_ENABLED=true
33
21
  ```
34
22
 
35
- Or with yarn:
23
+ These are distinct from the app's own Supabase credentials (`VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY`), which are used for the app's own auth and data and must remain in `.env` alongside these.
36
24
 
37
- ```bash
38
- yarn add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
39
- ```
25
+ > **Note:** Because Vite does not substitute env vars inside pre-bundled npm packages, `configureFeedbackClient()` must be called from within the host project's own source (see section 3). This is what makes the env vars available to the package at runtime.
40
26
 
41
- Or with pnpm:
27
+ **Next.js users:** use `NEXT_PUBLIC_` instead of `VITE_`:
42
28
 
43
- ```bash
44
- pnpm add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
29
+ ```env
30
+ NEXT_PUBLIC_FEEDBACK_SUPABASE_URL=https://<your-supabase-project>.supabase.co
31
+ NEXT_PUBLIC_FEEDBACK_SUPABASE_ANON_KEY=<your-anon-key>
32
+ NEXT_PUBLIC_FEEDBACK_PROJECT_ID=<your-project-id>
33
+ NEXT_PUBLIC_FEEDBACK_ENABLED=true
45
34
  ```
46
35
 
47
- > **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.
48
-
49
- ### Upgrading from 2.x to 3.x
50
-
51
- - **`FeedbackAdminPage` was removed** from the package. Remove any import and route; use [`apps/projectinablitz-frontend`](./apps/projectinablitz-frontend/) (or deploy it separately).
52
- - **`getSupabaseClient`** is now exported if you need direct Supabase access in advanced integrations.
53
-
54
- ## Quick Start
55
-
56
- **Host app integration (typical):** install the package, add Supabase URL + anon key to `.env`, wrap the app with `FeedbackAuthProvider` / `FeedbackProvider`, and pass the `project_id` string from your operator. You do **not** need to run database migrations in your repo—that happens on the Supabase project (see below if you operate that backend). The in-app setup page at `/readme` (`FeedbackReadmePage`) describes only this flow; full operator steps stay in this README.
57
-
58
- ### 1. Environment variables (host project)
59
-
60
- Add these to your **host project's** `.env` file (not this package):
61
-
62
- **Vite / Create React App:**
63
- ```
64
- VITE_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
65
- VITE_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key
66
- ```
67
-
68
- **Next.js:**
69
- ```
70
- NEXT_PUBLIC_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
71
- NEXT_PUBLIC_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key
72
- ```
73
-
74
- Get these from Supabase: Project Settings → API. Use the `anon` (public) key.
75
-
76
- **TypeScript users:** Add type definitions for these environment variables. For Vite projects, create `src/vite-env.d.ts`:
36
+ **TypeScript users:** add type declarations for these env vars. For Vite, in `src/vite-env.d.ts`:
77
37
 
78
38
  ```typescript
79
39
  /// <reference types="vite/client" />
@@ -81,31 +41,37 @@ Get these from Supabase: Project Settings → API. Use the `anon` (public) key.
81
41
  interface ImportMetaEnv {
82
42
  readonly VITE_FEEDBACK_SUPABASE_URL: string
83
43
  readonly VITE_FEEDBACK_SUPABASE_ANON_KEY: string
44
+ readonly VITE_FEEDBACK_PROJECT_ID: string
45
+ readonly VITE_FEEDBACK_ENABLED: string
84
46
  }
85
47
  ```
86
48
 
87
- For Next.js, add to `next-env.d.ts` or create a similar declaration file.
49
+ ---
88
50
 
89
- Alternatively, call `configureFeedbackClient({ url, anonKey })` at app init.
51
+ ## 2. Installation
90
52
 
91
- ### 2. Database migrations
53
+ ```bash
54
+ npm install @rensblitz/customer-instant-feedback-app
55
+ ```
92
56
 
93
- Run these SQL files in your Supabase SQL editor, in order:
57
+ The package requires these peer dependencies, which are already present in this project:
94
58
 
95
- 1. `migrations/schema_central.sql` – Creates tables
96
- 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.
97
- 3. `migrations/rls_central.sql` – RLS policies
98
- 4. `migrations/create_admin.sql` – Creates your first admin (replace placeholder UUID)
59
+ - `react` ^18
60
+ - `react-dom` ^18
61
+ - `react-router-dom` ^6
62
+ - `@supabase/supabase-js` ^2
99
63
 
100
- ### 3. Admin reviewer provisioning (hosted admin portal)
64
+ Also import the stylesheet once in the app entry point:
101
65
 
102
- **projectinablitz** in this monorepo talks to **projectinablitz-backend** (Spring Boot) to create/delete reviewer accounts; Supabase Edge Functions for that were removed.
66
+ ```tsx
67
+ import '@rensblitz/customer-instant-feedback-app/style.css'
68
+ ```
103
69
 
104
- If you embed only the npm package in your own app, you still use Supabase Auth + RLS as before; run the SQL migrations above. For reviewer lifecycle in a custom admin UI, call your own backend or Supabase Admin APIs with appropriate controls.
70
+ ---
105
71
 
106
- ### 4. Wrap your app
72
+ ## 3. App.tsx setup
107
73
 
108
- In your root component (e.g. `App.tsx` or `main.tsx`):
74
+ ### Imports
109
75
 
110
76
  ```tsx
111
77
  import {
@@ -113,189 +79,90 @@ import {
113
79
  FeedbackProvider,
114
80
  FeedbackLoginPage,
115
81
  FeedbackReviewPage,
116
- } from '@rensblitz/customer-instant-feedback-app';
117
- import '@rensblitz/customer-instant-feedback-app/style.css';
118
- import { BrowserRouter, Routes, Route } from 'react-router-dom';
119
-
120
- const projectId = 'your-project-id';
121
-
122
- function App() {
123
- return (
124
- <FeedbackAuthProvider>
125
- <BrowserRouter>
126
- <Routes>
127
- <Route path="/feedback-login" element={<FeedbackLoginPage />} />
128
- <Route path="/feedback" element={<FeedbackReviewPage projectId={projectId} />} />
129
- <Route
130
- path="/*"
131
- element={
132
- <FeedbackProvider projectId={projectId} feedbackReviewPath="/feedback">
133
- <YourApp />
134
- </FeedbackProvider>
135
- }
136
- />
137
- </Routes>
138
- </BrowserRouter>
139
- </FeedbackAuthProvider>
140
- );
141
- }
82
+ configureFeedbackClient,
83
+ } from '@rensblitz/customer-instant-feedback-app'
84
+ import '@rensblitz/customer-instant-feedback-app/style.css'
142
85
  ```
143
86
 
144
- **Operator UI** (companies, projects, reviewers) is **not** part of the npm package. Run [`apps/projectinablitz-frontend`](./apps/projectinablitz-frontend/) locally or deploy it separately (e.g. Render).
145
-
146
- **Important:** Always import the CSS file. Without it, the feedback modal has no styles.
87
+ ### Client configuration (module level, after all imports)
147
88
 
148
- ### 5. Get your project ID
149
-
150
- Use **projectinablitz** (in `apps/projectinablitz-frontend/` in this repo) to create a company and project, then copy the `project_id` (format: `short-code_uuid`) and pass it to `FeedbackProvider` and `FeedbackReviewPage`.
151
-
152
- ### 6. Create the first admin
153
-
154
- 1. Create a user in Supabase: Authentication → Users → Add user (email + password)
155
- 2. Copy the user's UUID
156
- 3. Run the SQL from `migrations/create_admin.sql` (replace the placeholder UUID)
157
-
158
- ## How it works
159
-
160
- - **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).
161
- - **Operators** use **projectinablitz** (`apps/projectinablitz-frontend/` in this repository, or your deployed instance) to manage companies, projects, and reviewers. Only users in the `admins` table can access it.
162
- - **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.
163
-
164
- ## Usage
165
-
166
- ### FeedbackProvider props
89
+ Call this once at module level — outside any component or function — so the package has its Supabase credentials before it initialises:
167
90
 
168
91
  ```tsx
169
- <FeedbackProvider
170
- projectId="acme-dash_abc123-uuid" // Required for full functionality
171
- enabled={true}
172
- rateLimitSeconds={30}
173
- validation={{
174
- maxCommentLength: 2000,
175
- maxNameLength: 100,
176
- maxScreenshotSize: 500000,
177
- }}
178
- >
179
- <YourApp />
180
- </FeedbackProvider>
92
+ configureFeedbackClient({
93
+ url: import.meta.env.VITE_FEEDBACK_SUPABASE_URL,
94
+ anonKey: import.meta.env.VITE_FEEDBACK_SUPABASE_ANON_KEY,
95
+ })
181
96
  ```
182
97
 
183
- - **projectId**: The project identifier from projectinablitz (or your own tooling). If omitted, a warning banner is shown.
184
- - **enabled**: Toggle the feedback feature on/off.
185
- - **feedbackReviewPath**: Path to the feedback review page (default: `/feedback`). Used for the "View all" link in the feedback toolbar.
186
- - **rateLimitSeconds**: Minimum seconds between submissions.
187
- - **validation**: Input validation limits.
98
+ ### Component tree structure
188
99
 
189
- ### Rate limiting
100
+ The full provider/route structure in `App.tsx`:
190
101
 
191
102
  ```tsx
192
- <FeedbackProvider projectId="..." rateLimitSeconds={60}>
193
- <YourApp />
194
- </FeedbackProvider>
195
- ```
196
-
197
- ### Validation
198
-
199
- ```tsx
200
- <FeedbackProvider
201
- projectId="..."
202
- validation={{
203
- maxCommentLength: 500,
204
- maxNameLength: 50,
205
- allowScreenshots: true,
206
- maxScreenshotSize: 1024 * 1024,
207
- }}
208
- >
209
- <YourApp />
210
- </FeedbackProvider>
211
- ```
212
-
213
- ## Migrations (central Supabase project)
214
-
215
- Run these migrations in your Supabase SQL editor, in order:
216
-
217
- 1. `migrations/schema_central.sql` – Creates companies, projects, admins, reviewers, and feedback_items tables
218
- 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.
219
- 3. `migrations/rls_central.sql` – RLS policies
220
- 4. `migrations/create_admin.sql` – Template for creating first admin(s)
221
-
222
- ## TypeScript types
223
-
224
- ```typescript
225
- interface ValidationConfig {
226
- maxCommentLength?: number;
227
- maxNameLength?: number;
228
- allowScreenshots?: boolean;
229
- maxScreenshotSize?: number;
230
- }
103
+ function App() {
104
+ return (
105
+ <FeedbackAuthProvider> {/* outermost — manages reviewer auth state */}
106
+ <BrowserRouter>
107
+ <Routes>
231
108
 
232
- interface FeedbackProviderProps {
233
- children: React.ReactNode;
234
- projectId?: string;
235
- enabled?: boolean;
236
- rateLimitSeconds?: number;
237
- validation?: ValidationConfig;
238
- feedbackReviewPath?: string;
239
- }
109
+ {/* Feedback-specific routes — rendered outside FeedbackProvider intentionally */}
110
+ <Route path="/feedback-login" element={<FeedbackLoginPage />} />
111
+ <Route path="/feedback" element={<FeedbackReviewPage projectId={import.meta.env.VITE_FEEDBACK_PROJECT_ID} />} />
112
+
113
+ {/* All app routes — wrapped with FeedbackProvider so the widget appears on every page */}
114
+ <Route path="*" element={
115
+ <FeedbackProvider
116
+ projectId={import.meta.env.VITE_FEEDBACK_PROJECT_ID}
117
+ rateLimitSeconds={30}
118
+ enabled={import.meta.env.VITE_FEEDBACK_ENABLED === 'true'}
119
+ feedbackReviewPath="/feedback"
120
+ >
121
+ {/* rest of the app */}
122
+ </FeedbackProvider>
123
+ } />
240
124
 
241
- interface FeedbackReviewPageProps {
242
- projectId: string;
125
+ </Routes>
126
+ </BrowserRouter>
127
+ </FeedbackAuthProvider>
128
+ )
243
129
  }
244
130
  ```
245
131
 
246
- ## Development
247
-
248
- ### Testing the library locally
132
+ ### FeedbackProvider props
249
133
 
250
- The `apps/demo/` folder contains a separate app that imports the library like a real consumer would:
134
+ | Prop | Type | Description |
135
+ |---|---|---|
136
+ | `projectId` | `string` | Project ID from projectinablitz. Required for feedback to be stored correctly. |
137
+ | `enabled` | `boolean` | Toggle the widget on/off without redeployment. Driven by `VITE_FEEDBACK_ENABLED`. |
138
+ | `rateLimitSeconds` | `number` | Minimum seconds between submissions per reviewer. |
139
+ | `feedbackReviewPath` | `string` | Path to the review page. Used for the "View all" link in the widget. |
140
+ | `validation` | `object` | Optional. Limits: `maxCommentLength`, `maxNameLength`, `allowScreenshots`, `maxScreenshotSize`. |
251
141
 
252
- 1. **First time setup:**
253
- ```bash
254
- npm run demo:install
255
- npm link
256
- cd demo && npm link @rensblitz/customer-instant-feedback-app
257
- ```
258
- Add `VITE_FEEDBACK_SUPABASE_URL` and `VITE_FEEDBACK_SUPABASE_ANON_KEY` to `apps/demo/.env` (copy from `apps/demo/.env.example` if present).
142
+ ---
259
143
 
260
- 2. **Build the library:**
261
- ```bash
262
- npm run build
263
- ```
144
+ ## 4. Reviewer flow
264
145
 
265
- 3. **Run the demo app:**
266
- ```bash
267
- npm run demo
268
- ```
146
+ - Reviewers navigate to `/feedback-login` and sign in with credentials provisioned by an admin.
147
+ - Once logged in, the feedback widget becomes visible on all app pages (wherever `FeedbackProvider` wraps the UI).
148
+ - Reviewers can visit `/feedback` to see all submitted feedback for the project.
269
149
 
270
- The demo app imports from `node_modules` using `npm link`, so it works exactly like a real host app.
150
+ ---
271
151
 
272
- **After making changes to the library:**
273
- - Rebuild: `npm run build`
274
- - The demo will hot-reload automatically
152
+ ## 5. Managing companies, projects, and reviewers
275
153
 
276
- **Demo includes** (typical host routes; see `apps/demo/`):
277
- - `/feedback-login` - Login page for reviewers
278
- - `/feedback` - Feedback review page
279
- - `/readme` - Setup guide (also available as `FeedbackReadmePage` for host apps)
280
- - `/` - Demo page with the feedback widget
154
+ The operator UI (**projectinablitz**) is a separate application that lives in the package's monorepo (`apps/projectinablitz-frontend`). It is not part of this project. Use it to:
281
155
 
282
- **projectinablitz** is a separate Vite app: run `npm run dev:frontend` from the repo root.
156
+ - Create companies and projects (which gives you the `project_id` to use in the env)
157
+ - Provision and manage reviewer accounts
283
158
 
284
- ### Building for npm
159
+ ---
285
160
 
286
- ```bash
287
- npm run build
288
- ```
161
+ ## 6. Toggling feedback off
289
162
 
290
- Builds the library (ESM, CommonJS, TypeScript declarations, CSS).
291
-
292
- ### Publishing to npm
293
-
294
- ```bash
295
- npm publish --access public
296
- ```
163
+ Set `VITE_FEEDBACK_ENABLED=false` in `frontend/.env` and restart the Vite dev server. The widget will not render. All other feedback infrastructure (routes, providers) remains in place but is inert.
297
164
 
298
- The package is configured for npm distribution with proper exports.
165
+ ---
299
166
 
300
167
  ## License
301
168
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rensblitz/customer-instant-feedback-app",
3
- "version": "3.1.0",
3
+ "version": "3.1.1",
4
4
  "description": "A React component library for collecting user feedback with screenshots and annotations",
5
5
  "author": "Rens Blitz",
6
6
  "license": "MIT",