SonarCloud's Automatic Analysis is off. The new `sonarcloud` job in ci.yml runs SonarSource/sonarqube-scan-action v8.3.0 after `check`, with the LCOV report that `check` now uploads; it never installs npm packages, so SONAR_TOKEN never shares a job with them, and it fails with the quality gate. Fork and Dependabot PRs skip it (no repository secrets). sonar-project.properties analyses the tests as tests, imports the coverage and excludes from it everything Vitest does not measure. Vitest now also measures src/config, src/store and src/utils, next to the engine, the Worker and the build plugins. The job passes package.json's version as sonar.projectVersion, so the "previous version" new-code period starts again at every release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
23 KiB
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.jsonfor autocomplete). - Settings → Languages → TypeScript → keep the IDE's bundled TypeScript service.
node_modules/typescriptis 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 typecheckis the source of truth. - Settings → Code Style → Prettier → Run on save (
{src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css}— the same filesnpm run formatcovers).
VS Code
Recommended extensions (no .vscode/extensions.json is committed — install manually):
dbaeumer.vscode-eslintesbenp.prettier-vscodebradlc.vscode-tailwindcssrust-lang.rust-analyzer(if you touchsrc-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 againstmain. There is no other long-lived branch, and every merge tomaindeploys the web app. - PR titles use the commit format
type(scope): message; CI checks them. - Every PR runs the
checkjob (below),dependency-review,workflow-lint,reuseandpr-title; the Rust jobslint-and-testandcargo-denyrun whensrc-tauri/changes. - After
check, thesonarcloudjob sends the code and the coverage report to SonarCloud (settings insonar-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 noSONAR_TOKEN— andmainis analysed after every merge.
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/ (lcov.info is what SonarCloud reads); fails below the thresholds for src/engine/ and worker/ set in vitest.config.ts. It measures the logic layers — src/engine, src/config, src/store, src/utils, worker/, build-plugins/; sonar-project.properties excludes everything else from SonarCloud's coverage, so a new source folder goes into one list or the other. 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 keepsTURNSTILE_SECRETas a Cloudflare Secret.- Without
.dev.varsthe Worker has noTURNSTILE_SECRETand fails open: the app loads without the gate. - The Worker serves the last build — run
npm run buildagain 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
- ARCHITECTURE.md — layer model, data flow, engine design.
- HOSTING.md — how ytgenerator.stream is built, deployed and protected.
- I18N.md — adding new languages step-by-step.
- PACKAGING.md — Tauri release builds and signing.
- Top-level CONTRIBUTING.md — PR process, commit conventions, auto-ignore rules.
- Top-level SECURITY.md — reporting vulnerabilities.