Klippy

Dependencies

Klippy is a Next.js (App Router) app that runs entirely in the browser with optional server‑side proxies for stock media and AI. This page lists runtime and dev dependencies, required system tooling, and common installation issues on macOS, Linux, and Windows.

1) Runtime matrix

  • Node.js: 18–20 (recommended: 20 LTS). Node 21/22 may work but are not required.
  • Browsers (latest): Chrome/Edge (best performance), Firefox, Safari (performance varies).
  • OS: macOS, Linux, Windows 10/11 (native, Git Bash, or WSL2).

2) Core packages

UI / Framework

  • next@15 — App Router, Edge routes
  • react@19 / react-dom@19
  • tailwindcss@3 — styling + theme tokens in globals.css
  • lucide-react — icons

State / Data

  • @reduxjs/toolkit, react-redux — project/timeline state, history batching
  • idb — local storage (IndexedDB)
  • zod — schema validation

Media / Export

  • @ffmpeg/core, @ffmpeg/ffmpeg, @ffmpeg/util — WASM export (MP4/WebM/GIF)
  • mp4-muxer, webm-muxer — container helpers
  • mediabunny — mobile‑first conversions (optional)
  • react-moveable/moveable — element transform UI
  • @remotion/* — preview player/utils for animations

AI / Analytics (optional)

  • @tensorflow/*, MediaPipe models — background/pose features
  • posthog-js — product analytics
  • @sentry/nextjs — error monitoring
  • @upstash/redis — rate limiting middleware
Full list with versions: see package.json in the repo root.

3) Scripts

  • npm run dev — dev server (macOS/Linux, kills existing port)
  • npm run dev:clean — dev server without turbo (use for E2E)
  • npm run dev:win — dev server on Windows (PowerShell/CMD)
  • npm run build — production build
  • npm start — start production server
  • npm run lint, npm test, npm run test:e2e

4) System tooling (when needed)

The app itself does not require global FFmpeg or ImageMagick. Some dev dependencies (e.g., canvas for tests) may need native build tools on Windows.

macOS / Linux

  • Node via nvm
  • Optional: lsof (used by dev script)
  • Optional (tests): build tools for native modules

Windows

  • nvm‑windows to install Node 20
  • Visual Studio Build Tools (Desktop C++ workload) — only if tests need canvas
  • Alternative: Run dev/tests in WSL2 Ubuntu for smoother native builds

5) External services

Keys live server‑side (no NEXT_PUBLIC_ prefix) and are accessed through Next API routes.

# Stock media
PEXELS_API_KEY=...
TENOR_API_KEY=...
TENOR_CLIENT_KEY=clip-js
MEME_API_KEY=...

# Site & CORS (prod)
NEXT_PUBLIC_SITE_URL=https://your-domain
ALLOWED_ORIGINS=https://your-domain,https://www.your-domain
CSP and allowed domains are configured in middleware.ts (images/media/connect‑src allowlists).

6) WASM & static assets

  • FFmpeg core files are served from /public/wasm and must have MIME application/wasm.
  • Next config and public/_headers set correct content‑type; Service Worker pre‑caches in production.
  • CDN fallback can be enabled: NEXT_PUBLIC_FFMPEG_ALLOW_CDN=true.

7) Package inventory (auto‑generated)

Framework / UI (13)

Styling (5)

State / Data (4)

Media / Export (9)

Remotion (7)

AI / ML (7)

Analytics / Monitoring (3)

Networking / Auth / Logging (4)

Images (1)

TypeScript / Types (5)

Testing / E2E (10)

Lint / Build (7)

Other (19)

Source: package.json in this repository (rendered on the server, grouped client‑side).

8) Troubleshooting install/build

Node version mismatch

Use Node 18–20. Switch using nvm / nvm‑windows. Clear modules if needed: rm -rf node_modules package-lock.json && npm install.

Windows: native build failed (canvas/node-gyp)

Install Visual Studio Build Tools (Desktop C++), Python 3, and retry. Or run tests in WSL2.

sharp/libvips errors during install

Ensure network can download prebuilt binaries. Try npm config set sharp_binary_host "https://npm.taobao.org/mirrors/sharp" or reinstall: npm rebuild sharp --verbose.

Playwright browsers not installed

Run npx playwright install. On Windows, use an elevated PowerShell or WSL2 if corporate policies block downloads.

FFmpeg WASM 404 or downloads as octet‑stream

Verify /wasm/ffmpeg-core.wasm is served with application/wasm and that next.config.js rewrites are loaded.

403 Unauthorized origin for Tenor/Meme

Set NEXT_PUBLIC_SITE_URL and ALLOWED_ORIGINS to include your domain. For Electron/file:// set ALLOW_NULL_ORIGIN=true.

Out of memory while building

Increase Node memory: macOS/Linux NODE_OPTIONS=--max-old-space-size=4096 npm run build; Windows (PowerShell) $env:NODE_OPTIONS='--max-old-space-size=4096'; npm run build.

9) FAQ

Do I need system FFmpeg?

No. Export uses @ffmpeg/ffmpeg (WebAssembly) in the browser.

Can I run without keys?

Yes — local upload/edit/export works. Stock media search just won’t return results.