vishiri/fantasia-dev-setup

Fantasia Archive — dev setup

Toolchain

• Package manager: Yarn 1.x (.github/workflows/verify.yml installs [email protected] for CI; match locally when practical). Avoid npm-only workflows for day-to-day work.
• Node.js: 22.22.0 or newer (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).
• Quasar CLI (recommended): yarn global add @quasar/cli — ensure the global Yarn bin is on PATH.
• CI (push/PR): .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.

Install

yarn

Run (development)

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

Troubleshooting

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

DevTools Autofill.enable / Autofill.setAddresses in the terminal

Bundled 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).

Production build

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 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 fixAppName.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 calls resetFaPlaywrightIsolatedUserData() (helpers/playwrightHelpers/playwrightUserDataReset.ts) before that group's 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 helpers live under helpers/playwrightHelpers/; add future harness packages as siblings under helpers/; 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.

Quick reference

| Goal | Command | |------|---------| | Quality gate (lint + vue-tsc + style + Vitest coverage: 100% src-electron + helpers; 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).

TypeScript interfaces and types (types/)

• Put shared 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).
• For JavaScript (.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.