Files
bookmarkmagic/docs/01_TECH_STACK.md
T
poli0981andClaude Opus 5 ad96b4f0f9 fix(deps): declare @types/node, which CI proved was never really there
The first CI run on this branch failed `npm run check` with 18 errors —
"Cannot find name 'node:fs'" — including in `tests/unit/styles/contrast.test.ts`,
which this branch never touched. So it was not the new test: the package has
always used Node types without declaring them.

Two things hid it. WXT 0.20 supplied `@types/node` transitively and 0.21 does
not, and this worktree sits under the parent checkout, so TypeScript walked up
to `E:\bookmarkmagic\node_modules\@types\node` and resolved them anyway — even
after a correct `npm ci` in the worktree itself. A green local type-check in a
worktree is therefore weaker evidence than it looks, which is now written down
in CLAUDE.md next to the existing worktree gotcha.

Types only: erased at build, nothing ships, so hard rule 2 — zero *runtime*
dependencies — is untouched, and the built manifest and bundle are unchanged.
docs/01 §2 records it with the reason, since that table is the pinned-version
spec rather than a summary of it.

This is the failure the tag run would otherwise have hit, and the reason a red
CI is worth reading before merging rather than after tagging.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-03 20:16:57 +07:00

7.1 KiB

01 — Tech Stack

Versions verified against npm/official sources on 2026-07-25. Rule: latest stable or LTS only, with any deliberate exception stated inline. Re-verify minor/patch at scaffold time (npm outdated), but do NOT jump majors without a doc update.

1. Runtime target

Item Choice Rationale
Browser Chrome / Chromium, Manifest V3 MV2 is fully retired. Edge/Brave/Vivaldi/Opera work from the same build.
Min Chrome minimum_chrome_version: "120" Margin over our highest hard-floor API, runtime.getContexts() (116+). scheduler.yield() (129+) is used only behind a nullish fallback, so it does not raise the floor — see 08 §7.
Runtime deps 0 (zero) DOMParser, Blob, URL, crypto.randomUUID cover all needs.

2. Toolchain (dev dependencies)

Tool Version (2026-07) Role
Node.js 24.x (Active LTS) Build runtime. Active LTS until Oct 2026, maintained to 2028-04-30. Node 26 is Current, not LTS — do not use for production tooling yet.
npm bundled with Node 24 (v11) Package manager. Commit package-lock.json.
WXT ^0.21.3 (was ^0.20.27 through v1.0.0) Extension framework: entrypoints, manifest generation, HMR, wxt zip, wxt submit. 0.x, so a minor is semver's breaking slot — and 0.21 was: wxt/testing split into wxt/testing/fake-browser and wxt/testing/vitest-plugin, and tabs.create is now typed as returning void. Both are dev-only. Never take a WXT bump without diffing the built manifest before and after (12 §2.3); tests/unit/manifest.test.ts reads wxt.config.ts and is structurally incapable of noticing.
TypeScript ~6.0.3 (strict) Deliberate exception to "latest stable": TS 7.0 went GA 2026-07-08 (7.0.2 is dist-tags.latest), but the Go-native compiler exposes no stable programmatic API yet and Microsoft's own GA post says Svelte/Volar toolchains "can only currently rely on TypeScript 6.0" — full support is deferred to 7.1. Since svelte-check is our template type authority, we hold on 6.x. Pin with ~ (patch-only). Revisit when TS 7.1 ships and svelte-check declares support.
Svelte ^5.56.4 UI, runes mode only ($state, $derived, $effect, $props).
@wxt-dev/module-svelte latest at scaffold WXT ↔ Svelte integration.
Biome 2.5.2 (pinned exact) Lint + format (replaces ESLint + Prettier). Install with npm i -D -E @biomejs/biome per Biome guidance.
svelte-check ^4.7.4 Type/template authority for .svelte files.
@types/node ^24 (matches the Node major) Types for node:fs, node:path, node:child_process and process, which the test suite and scripts/*.mjs genuinely use. Declared explicitly since 2026-08-03 — it used to arrive transitively, and WXT 0.21 stopped providing it. Types only: erased at build, so hard rule 2 (zero runtime dependencies) is untouched.
jsdom ^30 (was ^29 through v1.0.0) Test DOM. Not interchangeable — 02 §3 picks jsdom over happy-dom because the Netscape walk depends on parse5's implied-end-tag behaviour. A major bump runs tests/unit/dom-environment.test.ts first; if that canary fails, pin rather than loosen the test.
Knip ^6 (6.29.0 latest as of 2026-07) Dead code: unused files, exports, dependencies. Requires Node ≥ 20.19. v6 swapped the TypeScript backend for oxc-parser — confirm compilers.svelte is still the supported .svelte hook before scaffold (10 §4).
Vitest latest stable at scaffold Unit tests for src/lib/core.
@vitest/coverage-v8 match Vitest Coverage reporting.

3. Explicitly rejected

Rejected Why
Tailwind CSS Scoped Svelte styles + CSS custom properties suffice for a 5-tab app; avoids a build-time dependency and keeps the reviewable bundle tiny. (JSONPrism uses Tailwind because it is a large web app; different trade-off.)
React/Vue Svelte 5 is the established extension stack (SETWH precedent); smallest output.
ESLint + Prettier Replaced by Biome (portfolio standard).
Any bookmark-parsing npm package Netscape format is simple; owning the parser = owning round-trip fidelity + zero supply-chain surface.
chrome.downloads API Anchor-download (<a download> + Blob URL) works in extension pages with no extra permission. window.showSaveFilePicker() — also permission-free — covers the one case the anchor cannot: a confirmable write, used for the forced safety backup (03 §1 step 6b). Neither needs downloads.
Obfuscation tooling Prohibited by Chrome Web Store policy. Minify-only (WXT/Vite default).

4. Optional, gated additions (require explicit approval)

Package Trigger Notes
fflate v1.1 "export all formats as one .zip" Already trusted in JSONPrism. Tree-shakeable.
@types/chrome Only if WXT's bundled browser typings prove insufficient Prefer WXT's browser global.

5. package.json scripts (canonical)

{
  "license": "GPL-3.0-or-later",
  "engines": { "node": ">=24" },
  "scripts": {
    "postinstall": "wxt prepare",             // generates .wxt/tsconfig.json — 10 §2 extends it
    "dev": "wxt",
    "dev:firefox": "wxt -b firefox",          // build sanity only, no store release
    "build": "wxt build",
    "zip": "wxt zip",
    "check": "svelte-check --tsconfig ./tsconfig.json && tsc --noEmit",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "knip": "knip",
    "guard": "node scripts/guard.mjs",        // canonical grep gate, 08 §3
    "test": "vitest run",
    "test:watch": "vitest",
    "coverage": "vitest run --coverage",
    "verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
    "verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
  }
}

postinstall is not optional: tsconfig.json extends ./.wxt/tsconfig.json (10 §2), which does not exist until wxt prepare has run, so a clean npm ci would otherwise fail type-checking.

npm run verify is the local gate — it must pass before every commit that touches src/.

It is not the same gate CI and a release tag run, and the difference bites: both additionally run coverage (the 11 §1 thresholds), build and check:manifest. A change to src/lib/core/** that drops branch coverage below 85 therefore passes every local step and fails only after the tag is pushed — by which point release.yml may already have created the GitHub Release, which is not re-runnable. verify:full closes that gap and is what CLAUDE.md hard rule 8 requires before anything release-bearing.

Also set repository, homepage and bugs to https://github.com/poli0981/bookmarkmagic — 13/14 link to those URLs. Commit .nvmrc containing 24.

6. Version pinning policy

  • typescript → ~ (patch only; TS minors can break svelte-check).
  • @biomejs/biome → exact (-E), formatter output must be reproducible.
  • Everything else → ^, with package-lock.json committed as source of truth.
  • Renovate/Dependabot: weekly, grouped, majors require manual review.