video-downloader/CLAUDE.md

Approach

• Read existing files before writing. Don't re-read unless changed.
• Thorough in reasoning, concise in output.
• Skip files over 100KB unless required.
• No sycophantic openers or closing fluff.
• No emojis or em-dashes.
• Do not guess APIs, versions, flags, commit SHAs, or package names. Verify by reading code or docs before asserting.

Global

• Utilise Docker & Docker-Compose pour la base de données (MariaDB)
• On développe tout en NodeJS notamment avec : NextJS & Prisma pour la partie backend et React pour la partie frontend

Application : Ombrora-YTDLP

• Interface web publique permettant de soumettre des URLs de videos a telecharger via yt-dlp.
• Les telechargements sont geres via une file d'attente (queue) executee par Passenger en arriere-plan avec support du multithreading.
• Chaque telechargement est stocke en base de donnees (MariaDB via Prisma). Aucune entree n'est jamais supprimee : la DB conserve l'historique complet de tous les telechargements (statuts, erreurs, metadata).
• Le worker Passenger est responsable de dequeuer et d'executer yt-dlp en parallele selon la capacite configuree.

Deployment (o2switch)

• o2switch is shared hosting: no compiler toolchain, no root access. Any dependency with a native/binary component must ship as a precompiled binary — it cannot be built from source on the server.
• Before adding any new dependency with native bindings, confirm it publishes prebuilt binaries for o2switch's platform/arch — otherwise it will fail to install or run there.
• The o2switch nodevenv/Passenger setup ("Setup Node.js App" in cPanel) only supports a single package.json/node_modules for the whole registered app — not one per subfolder. Verified by directly debugging a failed frontend/ build: npm install --prefix frontend --include=dev (root's own build script) and even a plain npm install run with cd frontend first (confirmed via pwd to genuinely be inside frontend/) both completed "successfully" (correct, unmodified frontend/package-lock.json, real resolved entries for every package) yet never created a frontend/node_modules directory on the server at all. Meanwhile vite/@vitejs/plugin-react (already present as root devDependencies) resolved fine during the build — only packages that exist exclusively in frontend/package.json (react-router-dom, react-i18next, i18next, @phosphor-icons/react) failed to resolve, with Vite/Rolldown erroring Rolldown failed to resolve import "react-router-dom".
  • Fix (applied): every runtime package frontend/src/** imports must also be listed in the root package.json's dependencies (not just frontend/package.json's) — react/react-dom already were; react-router-dom, react-i18next, i18next, @phosphor-icons/react were added there too. Root's single node_modules is an ancestor directory of frontend/src/, so Node/Vite's normal upward node_modules resolution walk finds them there even with no frontend/node_modules on the server.
  • frontend/package.json still declares the same packages in its own dependencies — that's intentional, not stale duplication. It's what makes local dev (npm run dev inside frontend/, which gets a real, normal frontend/node_modules on a dev machine) work independently of this server-only constraint. When adding a new frontend runtime dependency, add it to both package.json files (frontend's own, for local dev; root's, for the o2switch build) and run npm install in both places to keep both lockfiles in sync.
  • frontend/package.json's devDependencies (vite, @vitejs/plugin-react, oxlint, @types/react*) do not need mirroring to root — only the ones already there (vite, @vitejs/plugin-react) are actually required for the production build to run at all; oxlint/@types/* are dev-only tooling never invoked during npm run build.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.