// Sets up and runs Fantasia Archive locally using Yarn, Node.js 22.22 or newer, and Quasar Electron mode. Use when installing dependencies, choosing dev vs production build commands, or when the user mentions environment setup, CLI, or first run.
| name | fantasia-dev-setup |
| description | Sets up and runs Fantasia Archive locally using Yarn, Node.js 22.22 or newer, and Quasar Electron mode. Use when installing dependencies, choosing dev vs production build commands, or when the user mentions environment setup, CLI, or first run. |
.github/workflows/verify.yml installs yarn@1.22.19 for CI; match locally when practical). Avoid npm-only workflows for day-to-day work.package.json engines.node is >=22.22.0; Quasar @quasar/app-vite v2 aligns with this). Use nvm / fnm to pin (e.g. nvm use 22.22).yarn global add @quasar/cli — ensure the global Yarn bin is on PATH..github/workflows/verify.yml runs yarn testbatch:verify only (installs .storybook-workspace for ESLint). Storybook VRT (yarn test:storybook:visual*) is not run in GitHub Actions — use yarn testbatch:ensure:nochange or the individual scripts locally.yarn
Hot reload and Electron debugging:
quasar dev -m electron
(package.json also exposes yarn quasar:dev:electron.)
To run Electron dev and Storybook together in one terminal, use yarn app:dev (concurrently: prefixed logs; stopping one process stops both when -k applies).
Electron failed to install correctly (missing node_modules/electron/dist)The electron package downloads its binary in a postinstall step. npm install --ignore-scripts (or any install that skips lifecycle scripts) leaves path.txt / dist/ missing and Quasar will crash when spawning Electron.
Fix: remove the broken folder and reinstall with scripts enabled (close running Electron/Quasar first if Windows reports EBUSY):
rm -rf node_modules/electron # PowerShell: Remove-Item -Recurse -Force node_modules/electron
yarn install
# or: node node_modules/electron/install.js
Autofill.enable / Autofill.setAddresses in the terminalBundled DevTools call Chrome CDP domains that Electron does not implement; Chromium logs harmless failures to stderr. The app filters those specific lines in the Electron main process so the dev terminal stays readable (they can still appear inside the DevTools console itself).
Required for packaged app behavior and before Playwright component/e2e runs:
quasar build -m electron
(yarn quasar:build:electron maps to quasar build -m electron --publish never.)
Quieter / chained runs: yarn quasar:build:electron:summarized runs the same build via .utility-scripts/quasarBuildElectronSummarized.mjs: one success line, full log under test-results/quasar-build-electron-last.log (printed on failure). yarn testbatch:ensure:nochange and yarn testbatch:ensure:change use this script.
Playwright userData: With TEST_ENV components or e2e, Electron userData is %APPDATA%/<package.json name>/playwright-user-data (here: Roaming\fantasia-archive\playwright-user-data), not fantasia-archive-dev (that folder is for quasar dev when DEBUGGING is set). See appIdentity_manager.ts for main-process wiring and playwrightIsolatedUserDataDirName.ts for the shared folder-name constant (Electron-free, used by playwrightUserDataReset). Component and E2E specs group tests in test.describe.serial; each group's test.beforeAll **await**s launchFaPlaywrightComponentHarnessWindow / launchFaPlaywrightE2eAppWindow, which call resetFaPlaywrightIsolatedUserData() (helpers/playwrightHelpers_universal/playwrightUserDataReset.ts) before electron.launch, not in test.beforeEach — a per-test reset would wipe playwright-user-data on disk while the shared ElectronApplication still holds the old profile, diverging the running process from disk. Shared Playwright packages: helpers/playwrightHelpers_universal/, helpers/playwrightHelpers_e2e/, helpers/playwrightHelpers_component/; future non-Playwright helper packages belong as siblings under helpers/<name>/. Keep the repo root for config, README, lockfiles, and scripts/, not new loose harness .ts files. Rebuild the production Electron app after changing fixAppName path logic or playwrightIsolatedUserDataDirName.
| Goal | Command |
|---|---|
Quality gate (lint + vue-tsc + style + Vitest coverage: 100% src-electron + helpers corpus excluding playwright harness trees per vitest.helpers.config.mts; src .ts per vitest/; vue SFCs watermarks only; one terminal) | yarn testbatch:verify |
| Full project gate (verify + summarized Electron build + Playwright component + E2E + Storybook smoke + VRT compare) | yarn testbatch:ensure:nochange |
| Full project gate — refresh Storybook VRT baselines (same through smoke, then snapshot update) | yarn testbatch:ensure:change |
| ESLint | yarn lint:eslint |
TypeScript (vue-tsc, no emit; includes .vue SFCs) | yarn lint:typescript |
Stylelint (Vue/CSS/SCSS/Sass + Storybook .storybook sources) | yarn lint:stylelint (autofix: yarn lint:stylelint:fix) |
| Unit tests | yarn test:unit |
| Component tests (Playwright) | yarn test:components (after production build) |
| E2E tests (Playwright) | yarn test:e2e (after production build) |
Storybook nested package: run yarn at the repo root, then yarn --cwd .storybook-workspace install so yarn storybook:run / yarn storybook:build / yarn test:storybook:visual* (Playwright VRT) resolve their dependencies.
See eslint-typescript.mdc for ESLint vs TSLint, tsconfig / vue-tsc, and Vitest env typing. See fantasia-testing and vitest-tests.mdc for Playwright rebuild rules and layered Vitest coverage. Yarn 1.x reserves yarn check for dependency verification — use yarn testbatch:verify for the lint, types, stylelint, and Vitest-coverage gate (testing-terminal-isolation.mdc).
types/)interface / type declarations in repository-root types/ (import with app/types/...). Prefer one domain-oriented module per feature area with brief JSDoc on exports (see types/I_appMenusDataList.ts). Do not add colocated <filename>.types.ts under src/, src-electron/, or .storybook-workspace/. Ambient augmentations for third-party modules also live under types/ and are loaded with a side-effect import from the owning boot file or src/stores/index.ts (see types/piniaModuleAugmentation.ts)..js), TypeScript (.ts), Vue (.vue), and JSON (.json, .jsonc, .json5) files, enforce expanded multi-line object literals via ESLint (object-curly-newline + object-property-newline) and keep files auto-fixable with eslint --fix.Works on Fantasia Archive Electron main process: app lifecycle, window management, platform tweaks, native integrations, and ipcMain registration (register*Ipc + electron-ipc-bridge channel names). Use when editing electron-main.ts, src-electron/mainScripts/, or main-side tests.
Global keyboard shortcuts (faKeybinds): renderer matching, Pinia store, main-process persistence over IPC, and Keybind settings UI. Use when adding or changing app-wide shortcuts, capture validation, or bridge APIs for keybind storage.
Produces production Electron builds for Fantasia Archive with electron- builder and Quasar. Use when changing build scripts, packaging, or publish flags, or when the user asks how to ship the desktop app.
Runs and extends Fantasia Archive tests: Vitest unit tests vs Playwright component and E2E tests, including rebuild-before-Playwright rules and file naming. Use when writing tests, debugging CI, or when the user mentions Vitest, Playwright, component tests, or e2e.
Migrates Fantasia Archive features to two-level functions + managers layout: pure scripts/functions/, *_manager.ts wiring (underscore suffix, e.g. dialogFoo_manager.ts), thin Vue SFCs. Use when refactoring features, fixing fa-two-level ESLint violations, or adding new UI.
Designs SQLite usage in Fantasia Archive’s Electron main process: file locations under userData, native better-sqlite3 module constraints, and migrations. Use when editing electron-main database code, schema, or persistence paths.