# 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](https://ytgenerator.stream) by a Cloudflare Worker — see [HOSTING.md](./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](./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](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/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](https://rustup.rs/); 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 . |
### 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
```bash
# 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)](#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](https://sonarcloud.io/project/overview?id=poli0981_youtube-generator) (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](https://www.jetbrains.com/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](../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)](#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 `, 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:
```bash
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](#rust-checks).
## Cloudflare Worker (local)
The web app is served by a Cloudflare Worker ([`worker/`](../worker), configured in [`wrangler.jsonc`](../wrangler.jsonc)) that puts the Turnstile gate, the security headers and the public `/legal` pages in front of `dist/`. To run it locally:
```bash
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](./HOSTING.md).
## Tauri Desktop Build
See [PACKAGING.md](./PACKAGING.md) for the full release pipeline. Quick local build:
```bash
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):
```bash
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 .
### `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](./ARCHITECTURE.md) — layer model, data flow, engine design.
- [HOSTING.md](./HOSTING.md) — how ytgenerator.stream is built, deployed and protected.
- [I18N.md](./I18N.md) — adding new languages step-by-step.
- [PACKAGING.md](./PACKAGING.md) — Tauri release builds and signing.
- [Top-level CONTRIBUTING.md](../CONTRIBUTING.md) — PR process, commit conventions, auto-ignore rules.
- [Top-level SECURITY.md](../SECURITY.md) — reporting vulnerabilities.
- [Top-level ACCESSIBILITY.md](../ACCESSIBILITY.md) — what works with assistive technology, and the checklist for UI changes.