Files
youtube-generator/docs/DEVELOPMENT.md
T
poli0981andClaude Opus 4.8 9554dcc7af chore(deps): upgrade vite 7->8 to patch esbuild advisories (v0.27.1)
Resolves the 4 high-severity esbuild advisories (GHSA-gv7w-rqvm-qjhr,
GHSA-g7r4-m6w7-qqqr) deferred from v0.27.0. esbuild 0.17.0-0.28.0 is
vulnerable; the fix (0.28.1) is only reachable via vite 8 -- vite 7.3.3
pins esbuild ^0.27.0 and cannot reach it. Dev-server-only; the shipped
static bundle was never affected. npm audit: 4 high -> 0.

- vite ^7.3.3 -> ^8.0.16, @vitejs/plugin-react ^4.3.0 -> ^5.2.0,
  tsx ^4.16.0 -> ^4.22.4 (vitest 4.1.8 already supports vite 8)
- vite 8 bundles with Rolldown: manualChunks object form -> function
  form (vite.config.ts) is the only source change required
- Full gate chain green (typecheck, lint, knip, validate:locales,
  500/500 tests, build); dev/preview + Tauri-context build verified
- Bump 5 manifests 0.27.0 -> 0.27.1; CHANGELOG + stack-version docs

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-13 19:43:39 +07:00

6.0 KiB
Raw Blame History

Development Guide

This guide covers setting up YTDescGen for local development on Windows, macOS, or Linux. The application is a Vite/React web app with an optional Tauri desktop shell.

Reference Workstation

The reference workstation used to develop and ship this project:

Component Spec
OS Windows 11 Pro (24H2 or newer)
CPU Modern x86-64 — 6+ cores with AVX2 (Intel 11th-gen / AMD Zen 3 or newer)
GPU Discrete or integrated — Tauri's WebView2 backend runs fine on iGPU
RAM 16 GB minimum, 32 GB recommended for parallel typecheck + dev server
Storage 5 GB free for node_modules + Cargo target/ after a full Tauri build
Display 1920×1080 minimum; mobile-responsive layout tested down to 360×640

macOS and Linux work for development. Tauri release builds are cross-compiled or run on dedicated CI runners — see PACKAGING.md.

Toolchain

Install in this order:

Tool Version Why
Node.js >= 22.12.0 Vite 8 requires Node ^20.19 or >= 22.12. Use nvm or fnm.
npm bundled with Node 22 The project uses npm; pnpm and yarn are not tested.
Rust stable, >= 1.78 Required for the Tauri desktop build. Install via rustup.
Python 3.12 Optional — only needed for some Tauri platform tooling on Windows.
Tauri prerequisites per OS See https://v2.tauri.app/start/prerequisites/.

Windows specifics

  • Install Visual Studio Build Tools 2022 with the "Desktop development with C++" workload (required by tauri-build).
  • Install the WebView2 Runtime (usually pre-installed on Windows 11).
  • Long path support: git config --global core.longpaths true.

macOS specifics

  • Install Xcode Command Line Tools: xcode-select --install.

Linux specifics

  • Install per-distro Tauri prerequisites — libwebkit2gtk-4.1-dev, libappindicator3-dev, etc. See the Tauri docs linked above.

IDE Setup

The reference workflow uses JetBrains 2026.x IDEs (WebStorm or RustRover) as primary, with VS Code for quick edits.

JetBrains (WebStorm / RustRover / IntelliJ Ultimate)

  • Enable the Tailwind CSS plugin.
  • Enable the i18next plugin (or rely on src/i18n/locales/_schema.json for autocomplete).
  • Settings → Languages → TypeScript → "Use TypeScript from node_modules/typescript".
  • Settings → Code Style → Prettier → Run on save (src/**/*.{ts,tsx,json,css}).

VS Code

Recommended extensions (no .vscode/extensions.json is committed — install manually):

  • dbaeumer.vscode-eslint
  • esbenp.prettier-vscode
  • bradlc.vscode-tailwindcss
  • rust-lang.rust-analyzer (if you touch src-tauri/)
  • tauri-apps.tauri-vscode

First Run

# 1. Clone
git clone https://github.com/poli0981/youtube-generator.git
cd youtube-generator

# 2. Install web dependencies
npm install

# 3. Start the web dev server
npm run dev
# → http://localhost:5173

Common Commands

Command What it does
npm run dev Vite dev server, hot reload, web only.
npm run build Production web bundle into dist/.
npm run preview Serve the production bundle for sanity-testing.
npm run typecheck tsc --noEmit. Run before every PR.
npm run lint ESLint. Use npm run lint:fix to autofix.
npm run format Prettier write across src/.
npm run test Vitest watch mode.
npm run test:run Vitest single-run (for CI / pre-commit).
npm run test:coverage Coverage report into coverage/.
npm run validate:locales Enforces all 6 locales match _schema.json exactly. Must pass before any locale-touching PR merges.
npm run generate:locale Scaffold an empty locale from _schema.json for a new language.
npm run tauri:dev Tauri desktop in dev mode (auto-restarts on Rust or frontend changes).
npm run tauri:build Tauri release binary for the current platform.

Tauri Desktop Build

See PACKAGING.md for the full release pipeline. Quick local build:

npm run tauri:build
# Output: src-tauri/target/release/bundle/{msi,deb,dmg,app}

The first build takes ~5–10 minutes (cold Cargo cache). Subsequent builds are incremental.

Troubleshooting

validate:locales fails after adding a key

You forgot to update src/i18n/locales/_schema.json. The schema is the source of truth; locales must match it exactly.

Tauri build fails with link.exe not found (Windows)

Install Visual Studio Build Tools 2022 + Desktop C++ workload, then restart your shell so the new PATH is picked up.

Tauri build fails with pkg-config not found (Linux)

Install the per-distro Tauri prerequisites listed at https://v2.tauri.app/start/prerequisites/.

npm install is slow or hangs

Disable corporate VPNs / proxies that block the npm registry. The lock file is committed; offline installs work after one successful online install.

Hot reload not picking up locale edits

Locale JSON is bundled at build time, not watched. Restart the dev server after editing src/i18n/locales/*.

Since v0.26, only English ships in the main chunk; the other languages are lazy-loaded async chunks fetched on first use (see src/i18n/index.ts and docs/I18N.md). The restart advice above still applies to all of them.

Pre-commit hook fails on validate:locales but I didn't touch locales

You probably added a new key to _schema.json indirectly via the engine types (src/engine/types.ts → CONTENT_WARNINGS). New IDs require translations in all 6 locales.

See Also