# 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.

![Freedback Widget Demo](https://i.ibb.co/4g2MdLCZ/freedback-widget.gif)

[![👉 Live Demo](https://img.shields.io/badge/Live%20Demo-freedback.dev-blue)](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.

![Freedback Init Setup](https://i.ibb.co/ZvpTQjP/Screenshot-2025-05-31-at-0-54-57.png)

### 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 😍
```

![Freedback List Command](https://i.ibb.co/rGXs3gw0/Screenshot-2025-05-31-at-0-51-45.png)

### 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).

![Freedback AI Digest](https://i.ibb.co/cXFkT0YP/Screenshot-2025-05-31-at-0-52-41.png)

## 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