ShrimpReel — What It Is and How It Works

ShrimpReel is an open-source template for building SaaS websites that turn one photo into an AI-generated video following a viral trend (like a dance challenge). The idea: every trending keyword gets its own dedicated site, each built from this same template. You clone the repo, change the configuration, copy, and media, and you have a new site ready to launch.

Everything runs on Cloudflare's infrastructure — Workers (serverless code), D1 (database), R2 (object storage), KV (key-value store), Queues, Rate Limiting, and Cron Triggers. This means the entire stack is managed by Cloudflare, so you don't need your own servers.

Core Concept

• One photo → AI video: Users upload a single photo, and the site generates a short video that follows a predefined template (e.g., dancing as an elf in Santa's workshop).
• Per‑keyword sites: Each site targets a specific viral keyword (e.g., "Christmas Dance AI"). You create a new repo from this template, set the keyword, and ship.
• Monetization: Users pay for credits (one‑time packs or subscriptions) to generate videos. Payments are handled by third‑party providers (Waffo Pancake, Dodo Payments, or Stripe).

Tech Stack (Simplified)

• Frontend & Server‑Side Rendering: TanStack Start (React 19) + Tailwind CSS 4. The site is bilingual — English at /, Chinese at /zh.
• API: Hono (a lightweight web framework) handles all /api/* routes, media, sitemap, robots.txt, etc.
• Payments: Default is Waffo Pancake (a Merchant of Record, meaning they handle sales tax). Dodo Payments is an alternative. Stripe is also supported but you become the merchant and must handle tax yourself. For local development, a mock provider simulates payments.
• Video Generation: Uses fal.ai's queue API by default. Optional alternatives: yir.ai router or NanoAPI. A mock provider is used for local testing.

Main Features

Users & Credits

• Google sign‑in (including One Tap).
• Credit packs (one‑time purchases) and monthly/yearly subscriptions.
• A credit ledger tracks all transactions.
• User dashboard: view videos, billing, settings, redeem codes, invite links, account deletion, and data export.

Orders & Generation

• Full and partial refunds that claw back credits.
• A generation queue with a dead‑letter queue (for failed jobs).
• Credits are automatically returned if generation fails.

Growth & Analytics

• First‑ and last‑touch attribution (UTM parameters, ad click IDs).
• Funnel tracking: visit → sign‑up → checkout → paid → generate.
• GA4 events behind a consent banner.
• Public share pages for videos (opt‑in per video, with link previews).

Admin Panel

• Overview dashboard (including provider cost and gross margin).
• Manage users, orders, generations, takedowns, contact messages, payment events, emails, audit log, reports, redeem codes, referral leaderboard, runtime settings, and connection tests.
• Detailed views for users, orders, and generations with filters and search.

Email & Notifications

• Transactional emails: credits added, video ready, generation failed, refunded, takedown receipts.
• Admins get alerts for new takedowns, deadline reminders, and contact messages.
• Instant payment notifications via Telegram, Feishu, Discord, etc.

Compliance & Safety

• AI‑generated label on videos.
• Photos deleted after 7 days; videos after 30 days.
• Takedown requests processed on a 48‑hour queue (removes all videos made from the same source photo and blocks the photo).
• Upload moderation and Turnstile (CAPTCHA) on contact/report forms.

Operations & Security

• Maintenance mode, checkout pause, payment provider switch, site‑wide announcement, daily generation cap — all changeable from the admin without redeploying.
• Health‑check alert emails, daily D1 backups to R2, browser error reporting to Workers Logs.
• Content Security Policy (CSP) with per‑request nonce, and Permissions‑Policy.

Content & SEO

• One‑page home with sections: How it works, What is, plus optional problem/DIY blocks.
• Extensible article collection (/guides hub, related articles).
• Legal pages, contact form.
• SSR canonical, hreflang, JSON‑LD, sitemap.
• Copy is code‑split per locale (browser only loads the current language).
• npm run seo:check lints the whole site for SEO issues.

Local Development

To run the template locally:

npm install
cp .dev.vars.example .dev.vars   # set at least SESSION_SECRET
npm run seed:local               # apply database migrations and upload template media to local R2
npm run dev -- --host 127.0.0.1  # http://127.0.0.1:3000

• Use npm 11.19 or newer.
• By default, PAYMENT_PROVIDER=mock and VIDEO_PROVIDER=mock — no real charges or generation.
• A dev login is available outside production (POST /api/auth/dev-login).
• Email is simulated locally; check the outbox via GET /api/dev/emails?to=<email>&ref=<order or takedown id>.

Launching a New Site

The README provides a detailed 8‑step process. Here's the gist:

1. Create the site repo — clone the template, rename the remote to upstream, add your own origin.
2. Run the scaffolder — node scripts/new-site.mjs updates site.ts, wrangler.jsonc, and package.json with your keyword, domain, and other settings.
3. Rewrite the copy — edit src/content/en.ts and src/content/zh.ts to match the new trend. Don't just swap the keyword — Google penalizes scaled content abuse.
4. Replace media — upload your own template videos, demo videos, logos, etc.
5. Set environment variables in wrangler.jsonc (site URL, payment provider, admin emails, etc.).
6. Create products with your payment provider (credit packs and subscription plans).
7. Verify locally — run typecheck, tests, e2e, and SEO checks.
8. Deploy and then submit the sitemap to search engines.

There's also a Claude Code skill (new-hot-site) that automates steps 2–4 and the local part of step 7.

Merging Template Updates

Since each site is a separate repo that tracks the template as upstream, you can pull in fixes and new features:

git fetch upstream
git merge --no-ff upstream/main

A sync plan script (scripts/sync-plan.mjs) helps identify conflicts. Keep site‑specific changes in src/config/site.ts, src/content/*, public/*, seed/, wrangler.jsonc, and package.json — everything else should stay identical to the template.

Deploying to Cloudflare

You need to create the required Cloudflare resources (D1 database, R2 bucket, KV namespace, Queues) once per site, then run migrations and upload template media. The README gives exact commands.

Documentation & Notes

• Release notes: CHANGELOG.md
• Feature plans: docs/SAAS_VIDEO_FEATURES.md, ROADMAP.md
• SEO rules: docs/SEO_AUDIT.md
• Environment variables: docs/env.md
• Payment provider setup: docs/payments.md
• Subscription details: docs/subscriptions.md
• Code conventions: AGENTS.md

Most documentation files are in Chinese.

---

ShrimpReel is a complete, production‑ready template that handles everything from user authentication to video generation, payments, admin, and SEO — all on Cloudflare's free‑tier‑friendly stack. It's designed to be cloned and customized for each new viral trend, so you can launch a new site quickly.