FrenzSave.com
Premium multi-platform video downloader powered by yt-dlp. TikTok-first, with support for 1000+ platforms (Instagram, YouTube, X, Facebook, Reddit, Vimeo, SoundCloud and more).
Built with Next.js 15 (App Router), TypeScript, Tailwind CSS, Supabase, and Upstash Redis.
💙 Frenz Core — read this before building any feature. It is the mandatory
engineering foundation of the whole Frenzsave ecosystem: one backend, one identity, one cloud, one
security model, one design system. Every feature integrates with Frenz Core; nothing bypasses it.
✨ Features (current foundation)
- 🎯 Working downloader flow — paste → auto-detect platform → fetch metadata via yt-dlp → preview → choose format → stream download.
- 🧱 Enterprise architecture — feature-based modules, service layer (
server/services), repository-ready data access, SOLID-friendly separation.
- 🛡️ Security baked in — Zod validation, SSRF host filtering, sliding-window rate limiting (Upstash, with in-memory fallback), strict security headers.
- 🗄️ Supabase schema — profiles, downloads, analytics, traffic logs, settings, platform stats — with RLS policies, triggers, storage buckets, and realtime.
- 🎨 Premium landing page — glassmorphism, gradients, dark mode, mobile-first, animated, SEO-optimized (metadata, OG, JSON-LD, robots, dynamic sitemap).
- 🐳 Production infra — multi-stage Dockerfile (Next standalone + yt-dlp + ffmpeg), docker-compose (web + redis + nginx), nginx reverse proxy, GitHub Actions CI.
- ⚡ Instant-feel app shell — persistent
(app) layout (sidebar/topbar/modals render once; only content swaps → SPA-instant nav), content-only loading.tsx skeletons, SSR-seeded cached-first feed surfaces, and an SWR-style client cache (features/data). See docs/PERFORMANCE.md.
- 🔴 Realtime — live notification + messages badges, live conversation list and message thread (optimistic send) over Supabase channels (
features/social/inbox.ts).
- 🎬 Media pipeline — main media on Cloudflare R2 (
lib/storage, Supabase fallback) + optional Cloudflare Stream adaptive-bitrate video (lib/media/stream.ts, SmartVideo). See docs/INFRASTRUCTURE.md.
This is Phase 1: a runnable foundation. See Roadmap for what's intentionally stubbed for later phases.
🚀 Quick start (local)
Prerequisites
- Node.js ≥ 20
- yt-dlp on your
PATH (or set YTDLP_PATH)
- ffmpeg (required to merge video+audio and transcode audio)
Install yt-dlp + ffmpeg:
# macOS
brew install yt-dlp ffmpeg
# Windows (winget)
winget install yt-dlp.yt-dlp
winget install Gyan.FFmpeg
# Linux
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
sudo apt-get install -y ffmpeg
Run
npm install
cp .env.example .env.local # fill in values (Supabase/Upstash optional for first run)
npm run dev
Open http://localhost:3000. The downloader works without Supabase or Upstash configured — those add auth, history, and distributed rate limiting.
🗄️ Supabase setup
-
Create a project at supabase.com.
-
Run the migrations (Supabase CLI or SQL editor):
supabase db push
# or paste supabase/migrations/*.sql into the SQL editor in order
-
Copy your project URL + anon key + service role key into .env.local.
-
Enable the Google / GitHub providers under Authentication → Providers (Phase 2).
The schema lives in supabase/migrations/ and includes RLS, triggers (handle_new_user, bump_platform_stats), storage buckets, and a realtime publication on downloads.
🐳 Docker (recommended for production)
The Docker image bundles yt-dlp + ffmpeg, which is the most reliable way to run the streaming download endpoint.
cp .env.example .env.local # production values
docker compose up --build
This starts:
| Service | Port | Role |
|---|
web | 3000 | Next.js standalone server |
redis | 6379 | local cache (use Upstash in prod) |
nginx | 80 | reverse proxy + per-IP rate limiting |
▲ Production: Vercel frontend + Docker worker (the split)
Vercel's serverless runtime has no yt-dlp/ffmpeg, so the heavy routes run
on a Docker worker and Vercel proxies to it. The same codebase plays both
roles, decided purely by env:
| Role | Where | Env |
|---|
| Frontend | Vercel | DOWNLOAD_WORKER_URL=https://<worker> + WORKER_SECRET |
| Worker | Fly.io / Railway / VPS (Docker) | DOWNLOAD_WORKER_URL blank + same WORKER_SECRET |
When DOWNLOAD_WORKER_URL is set, /api/metadata and /api/download forward to
the worker (sending the secret); when blank, the app does the real
extraction/download itself. The worker rejects requests without a matching
x-worker-secret.
Deploy the worker (Fly.io example):
fly launch --no-deploy # creates the app from fly.toml
fly secrets set WORKER_SECRET=$(openssl rand -hex 24) \
UPSTASH_REDIS_REST_URL=... UPSTASH_REDIS_REST_TOKEN=...
fly deploy # builds Dockerfile (yt-dlp + ffmpeg)
Then point Vercel at it (Project → Settings → Environment Variables):
DOWNLOAD_WORKER_URL=https://<app>.fly.dev, the same WORKER_SECRET, plus
the rest of .env.example. Redeploy.
Note: Vercel Hobby caps function duration at 300s, so the proxied download
connection is capped there; full-length downloads still complete on the worker
if the client talks to it directly, or upgrade the plan.
Single-host alternative: skip Vercel and deploy only the Docker image
(docker compose up) — everything works in one place.
🧱 Project structure
app/ # App Router pages + route handlers + SEO (robots, sitemap)
api/ # metadata, download, health endpoints
components/ # Presentational UI (landing sections, layout chrome)
features/ # Feature modules (downloader: hook + UI)
lib/ # Cross-cutting utilities (platforms, validation, rate-limit, supabase)
server/services/ # Server-only service layer (yt-dlp wrapper)
supabase/migrations/ # SQL schema, RLS, triggers, storage, realtime
types/ # Shared domain types
middleware.ts # Supabase session refresh + /admin guard
🔐 Environment variables
See .env.example for the full annotated list. Highlights:
| Variable | Required | Purpose |
|---|
NEXT_PUBLIC_SITE_URL | ✅ | SEO / canonical / sitemap base |
NEXT_PUBLIC_SUPABASE_URL / _ANON_KEY | for auth | Supabase client |
SUPABASE_SERVICE_ROLE_KEY | for admin/cron | bypasses RLS — server only |
UPSTASH_REDIS_REST_URL / _TOKEN | prod | distributed rate limiting |
YTDLP_PATH | optional | path to yt-dlp binary |
🗺️ Roadmap
Phase 1 (this foundation) ships the downloader, schema, landing page, and infra. Planned next:
⚖️ Legal
Download only content you own or have the right to save, and respect each
platform's Terms of Service and applicable copyright law. This project is a
tool; responsibility for its use lies with the operator and end users. A DMCA
process and Terms/Privacy pages should be in place before public launch.
