freedback
Version:
A free, self-hosted feedback widget for Next.js apps with multiple storage options and AI-powered insights
159 lines (117 loc) • 4.39 kB
Markdown
# Freedback
A free, self-hosted feedback widget for Next.js apps. The CLI sets up everything you need to collect user feedback in your Next.js project using Supabase and shadcn/ui components.
[](https://freedback.dev)
## Features
- 🎨 **Customizable widget** - Instantly copy into your Next.js project
- 🎯 **Multiple modes** - Button overlay or inline display
- 💾 **Flexible storage** - Supabase database, email-only, or console logging
- 📧 **Email notifications** - Optional email alerts via Resend
- 🤖 **AI-powered insights** - Generate feedback summaries with OpenAI or Claude
- 📊 **Advanced filtering** - View feedback by date, emoji, or custom criteria
- 🛠️ **Zero dependencies** - Uses your own shadcn/ui components
- 🏗️ **Smart detection** - Automatic App Router vs Pages Router support
- 🔒 **Privacy-first** - You own your data, no third-party tracking
## Requirements
- Next.js 13+
- React 18+
- Tailwind CSS
- [shadcn/ui](https://ui.shadcn.com/) components (automatically installed if missing)
## Installation & Usage
### Quick Start
```sh
npx freedback@latest init
```
### Or install globally
```sh
npm install -g freedback
freedback init
```
## Storage Options
Choose how you want to handle feedback during setup:
### 🗄️ Supabase Database
- Stores feedback in your Supabase database
- Optional email notifications
- Full CLI management with `freedback list` and `freedback digest`
- **Requirements**: [Supabase](https://supabase.com/) project
### 📧 Email Only
- Sends feedback directly to your email
- No database required
- **Requirements**: [Resend](https://resend.com/) API key
### 🖥️ Console Only
- Logs feedback to browser console
- Perfect for development and testing
- No external services required
## CLI Commands
### Initialize Freedback
```sh
freedback init
```
Interactive setup wizard that configures your project.
### List Feedback
```sh
# Show recent feedback
freedback list
# Show last 20 entries
freedback list --limit 20
# Filter by date
freedback list --today
freedback list --week
freedback list --month
freedback list --since 2024-01-01
# Filter by emoji reaction
freedback list --emoji 😍
```
### AI-Powered Digest
```sh
# Generate AI summary of recent feedback
freedback digest
# Analyze this week's feedback
freedback digest --week
# Analyze specific timeframe
freedback digest --since 2024-01-01
```
Supports OpenAI (GPT-4o-mini) and Anthropic (Claude 3 Haiku).
## What does the setup do?
1. **Dependency Check** - Verifies Next.js, React, Tailwind CSS
2. **Component Setup** - Installs missing shadcn/ui components automatically
3. **Widget Customization** - Interactive prompts for title, button text, etc.
4. **Storage Configuration** - Choose and configure your preferred storage method
5. **Code Generation** - Copies widget and API routes to your project
6. **Environment Setup** - Creates/updates .env files with credentials
## Usage in Your App
After setup, add the widget to any component:
```tsx
import { Freedback } from '@/components/freedback';
// Basic usage (uses all defaults)
<Freedback />
// Button mode with custom text
<Freedback
buttonTitle="Send Feedback"
title="How can we improve?"
/>
// Inline mode
<Freedback
mode="inline"
title="Rate your experience"
/>
```
## Customization
The widget code is completely yours! Edit `components/freedback/index.tsx` to:
- Modify styling and layout
- Add custom validation
- Integrate with your design system
- Add additional form fields
## Architecture
- **Widget** → calls your `/api/feedback` endpoint
- **API Route** → handles storage (Supabase/Resend) and notifications
- **Server-side** → keeps credentials secure and enables management features
## Email Template
Includes beautiful HTML email templates with:
- Professional design using system fonts
- Comprehensive context (location, browser, viewport)
- Clickable URLs and metadata
- Consistent formatting with CLI output