Files
youtube-generator/docs/DEVELOPMENT.md
T
poli0981andClaude Opus 5.5 5a9e7e83de ci(qodana): add Qodana for TypeScript and Rust
A Qodana workflow with one job per Qodana Cloud project:
- typescript: Qodana for JS in native mode, on the runner's Node 26 and
  node_modules (qodana.yaml, project yt-ts-js, QODANA_TOKEN_TS_JS);
- rust: Qodana for Rust, Early Access, in Docker on src-tauri/
  (src-tauri/qodana.yaml, project yt-rust, QODANA_TOKEN_RUST). Its
  bootstrap installs what rust.yml installs; a stand-in dist/index.html
  lets generate_context!() expand.

Both use qodana.recommended with a quality gate of zero problems and
analyse the whole project on every run. A tokens job skips the analysis
for Dependabot and fork PRs, which get no secrets; the token reaches only
the scan step, never `npm ci`. Annotations and artifacts, no PR comment.
Failures reach Discord through notify-ci-failure.yml.

Docs: TECH-SPEC (workflow table, Qodana notes), DEVELOPMENT (+ vi),
CONTRIBUTING, CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:21:18 +07:00

22 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 shell for desktop and Android. On the web it is served at ytgenerator.stream by a Cloudflare Worker — see HOSTING.md.

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 26 — the version in .node-version CI, the release workflows and Cloudflare Workers Builds all read .node-version, and package.json declares engines.node >= 26. Use nvm or fnm (fnm reads .node-version).
npm 11, bundled with Node 26 The project uses npm; pnpm and yarn are not tested.
Rust stable, >= 1.90 Required for the Tauri desktop and Android builds (Tauri 2.12 needs Rust 1.90). Install via rustup; its default profile includes rustfmt and clippy.
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 → keep the IDE's bundled TypeScript service. node_modules/typescript is not the compiler: it is an npm alias for @typescript/typescript6, the TypeScript 6.0 API that typescript-eslint loads. The project type-checks with TypeScript 7 (tsc, from @typescript/native) — npm run typecheck is the source of truth.
  • Settings → Code Style → Prettier → Run on save ({src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css} — the same files npm run format covers).

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

The dev server is the app alone: no Turnstile gate and no analytics. To run the Worker that serves the web app, see Cloudflare Worker (local).

Branches and Pull Requests

  • Branch from main (feat/…, fix/…, docs/…, chore/…) and open the pull request against main. There is no other long-lived branch, and every merge to main deploys the web app.
  • PR titles use the commit format type(scope): message; CI checks them.
  • Every PR runs the check job (below), dependency-review, workflow-lint, reuse and pr-title; the Rust jobs lint-and-test and cargo-deny run when src-tauri/ changes.
  • After check, the sonarcloud job sends the code and the coverage report to SonarCloud (settings in sonar-project.properties) and fails when its quality gate does: new code needs A ratings, reviewed security hotspots, at most 3 % duplication and at least 80 % coverage. PRs from forks and from Dependabot skip it — they get no SONAR_TOKEN — and main is analysed after every merge.
  • The Qodana workflow runs JetBrains Qodana on every PR and every push to main: Qodana for JS on the repository (qodana.yaml) and Qodana for Rust on src-tauri/ (src-tauri/qodana.yaml). Both fail on any problem. Like SonarCloud, it skips PRs from forks and from Dependabot, which get no Qodana token. It is not a required check.

Full rules: CONTRIBUTING.md.

Common Commands

Develop and build

Command What it does
npm run dev Vite dev server, hot reload, web only.
npm run build tsc + production web bundle into dist/. The web build also gets the Web Analytics beacon, /.well-known/security.txt and the static /legal/* pages; builds started by the Tauri CLI leave them out.
npm run preview Serve the production bundle for sanity-testing (without the Worker).
npm run cf:dev wrangler dev — the Worker in front of dist/ on http://localhost:8787. See Cloudflare Worker (local).
npm run tauri:dev Tauri desktop in dev mode (also npm run tauri dev): starts npm run dev and opens the app window on it. Frontend changes hot-reload; Rust changes rebuild the app.
npm run tauri:build Tauri release binary for the current platform.

Check

Command What it does
npm run typecheck tsc --noEmit over src/ — what Vite actually builds.
npm run typecheck:all Same, plus tests/, scripts/, worker/ and build-plugins/ (tsconfig.check.json), which the base config deliberately excludes. Added in v0.35.0 after it turned out tests and scripts had never been type-checked — and immediately found three fields silently missing from the editor→engine parity fixture.
npm run lint ESLint over src/, tests/, scripts/, worker/ and build-plugins/. Use npm run lint:fix to autofix.
npm run format Prettier write across src/, tests/, scripts/, worker/ and build-plugins/ (.ts, .tsx, .css).
npm run format:check Same, read-only. CI gate. Markdown and the locale JSON are deliberately out of scope.
npm run knip Dead-code / unused-dependency check. CI gate.
npm run validate:locales Enforces all 8 locales match _schema.json exactly. Must pass before any locale-touching PR merges.
npm run test Vitest watch mode.
npm run test:run Vitest single-run.
npm run test:coverage Single run with a coverage report into coverage/ — the logic layers, and lcov.info goes to SonarCloud; fails below the thresholds for src/engine/ and worker/ set in vitest.config.ts. This is what CI runs.
npm run check:version Asserts all six version fields agree (package.json, both package-lock.json entries, tauri.conf.json, Cargo.toml, Cargo.lock). The only thing that notices a missed one.
npm run check:tauri The @tauri-apps/* npm packages and the Tauri crates must share major.minor. The Tauri CLI refuses to build otherwise, and CI never runs a Tauri build.
npm run check:licenses Every bundled package has an allowed license, and THIRD_PARTY_NOTICES.md matches what is installed.
npm run check:copyright NOTICE, REUSE.toml and the installers' copyright string (tauri.conf.json) state the copyright years for the year of HEAD's commit — "2026", then "2026-2027" from the first commit of 2027. CI gate (v1.1.0).
npm run check:bundle Run after npm run build: the initial load must stay ≤ 280 KB gzip and no JS chunk over 500 KB raw.
npm run cf:check wrangler deploy --dry-run: validates wrangler.jsonc and bundles the Worker the way Workers Builds will, without deploying.

Generate

Command What it does
npm run generate:locale Scaffold a locale from the English source. --lang <code>, plus optional --copy-english / --force. (Advertised since v0.1 but only actually written in v0.35.0.)
npm run generate:third-party Rewrite THIRD_PARTY_NOTICES.md from the installed packages — needed after a dependency change, or check:licenses fails.
npm run update:copyright Rewrite the copyright years in NOTICE, REUSE.toml and tauri.conf.json — needed with the first commit of a new year, or check:copyright fails.
npm run generate:brand Rasterise the brand SVGs in assets/brand/ into the web's PNG icons and link-preview card in public/. The PNGs are committed. The desktop and Android icons come from the same logo: npx tauri icon assets/brand/logo.svg.

Before You Open a PR

Run what CI's check job runs:

npm run typecheck && npm run typecheck:all
npm run lint && npm run format:check
npm run validate:locales
npm run test:coverage
npm run knip
npm run check:version && npm run check:tauri && npm run check:licenses
npm run check:copyright
npm run build && npm run check:bundle
npm run cf:check

Touched src-tauri/? Also run the Rust checks.

Cloudflare Worker (local)

The web app is served by a Cloudflare Worker (worker/, configured in wrangler.jsonc) that puts the Turnstile gate, the security headers and the public /legal pages in front of dist/. To run it locally:

cp .dev.vars.example .dev.vars   # Cloudflare's public Turnstile TEST keys only
npm run build                    # the Worker serves dist/
npm run cf:dev                   # wrangler dev → http://localhost:8787
  • .dev.vars (git-ignored) holds Cloudflare's published Turnstile test keys: the widget always passes and the secret only accepts the dummy token it produces. Never put the real secret in a file — production keeps TURNSTILE_SECRET as a Cloudflare Secret.
  • Without .dev.vars the Worker has no TURNSTILE_SECRET and fails open: the app loads without the gate.
  • The Worker serves the last build — run npm run build again to see frontend changes behind it.
  • Worker tests run with the rest of the suite (tests/worker/).

Deployment, cookies, headers, secrets and rollback: HOSTING.md.

Tauri Desktop Build

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

npm run tauri:build
# Output: src-tauri/target/release/bundle/
#   Windows: MSI + NSIS installers · Linux: deb, rpm, AppImage · macOS: .app + DMG

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

The Vite dev server does not watch src-tauri/** or .wrangler/** (server.watch.ignored in vite.config.ts): while tauri dev runs, Cargo rewrites files under src-tauri/target, and watching them crashed Vite on Windows with EBUSY on a locked .dll.

Rust checks

The same steps as the lint-and-test job in .github/workflows/rust.yml, which runs when src-tauri/ changes (and weekly):

npm run build          # tauri::generate_context!() embeds dist/, so clippy and the tests need a build
cd src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked

The cargo-deny job checks RustSec advisories, licenses and crate sources against src-tauri/deny.toml. Locally (after cargo install cargo-deny): cargo deny check advisories licenses sources in src-tauri/.

Troubleshooting

validate:locales fails after adding a key

You forgot to update src/i18n/locales/_schema.json, or one of the 8 locales. The schema is the source of truth; every locale must match it exactly.

validate:locales fails but I didn't touch locales

Someone — or a merge from main — added a key to _schema.json (for example the label of a new CONTENT_WARNINGS id from src/engine/types.ts) that isn't in every locale yet. New keys need a value in all 8 locales.

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/.

check:tauri fails after a dependency update

A @tauri-apps/* npm package moved to a new minor version without the crates (or the other way round). Run cargo update -p tauri (and the plugin crates check:tauri names) in src-tauri/ on the same branch.

check:bundle can't find dist/index.html

It measures a build — run npm run build first.

npm run cf:dev shows no Turnstile gate

.dev.vars is missing, so the Worker has no secret and serves the app without the gate. Copy .dev.vars.example to .dev.vars and restart.

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.

See Also