| 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. |
Fantasia Archive — dev setup
Toolchain
- Package manager: Yarn 1.x (CI:
yarn@1.22.19)
- Node.js: 22.22.0+ (
package.json engines.node >=22.22.0)
- Quasar CLI (optional global):
yarn global add @quasar/cli
- CI:
.github/workflows/verify.yml — yarn testbatch:verify only; Storybook VRT local only
Install
yarn
DnD libs (vue-draggable-plus, quasar-ui-q-draggable-table) in package.json; boot q-draggable-table. Policy: fantasia-drag-drop.
Run (development)
quasar dev -m electron
(yarn quasar:dev:electron). Electron + Storybook together: yarn app:dev.
Post-implementation agent gates (dev-electron-compile-check.mdc): (1) dev scoped gate (fantasia-dev-scoped-verify), (2) yarn quasar:dev:electron 20s compile smoke — separate terminals; kill agent-spawned dev after pass. Full yarn testbatch:verify only at final cleanup, commit, or explicit user request.
Troubleshooting
Electron failed to install correctly
Postinstall skipped → missing node_modules/electron/dist.
rm -rf node_modules/electron
yarn install
DevTools Autofill CDP noise
Harmless stderr; main process filters specific lines.
better-sqlite3 bindings missing
Native addon must match Electron ABI.
yarn rebuild:native
Close quasar dev first on Windows file locks. If still fails: remove node_modules/better-sqlite3, yarn install (scripts enabled), yarn rebuild:native again.
Production build
Required for packaged behavior + before Playwright:
quasar build -m electron
(yarn quasar:build:electron = quasar build -m electron --publish never).
Quieter: yarn quasar:build:electron:summarized — log in test-results/quasar-build-electron-last.log.
Playwright userData: TEST_ENV components/e2e → %APPDATA%/fantasia-archive/playwright-user-data. Serial suites reset in test.beforeAll only — see fantasia-testing.
Quick reference
| Goal | Command |
|---|
| Dev scoped gate (agents) | fantasia-dev-scoped-verify |
| Full quality gate | yarn testbatch:verify |
| Full project gate | yarn testbatch:ensure:nochange |
| Refresh Storybook VRT | yarn testbatch:ensure:change |
| ESLint | yarn lint:eslint |
| TypeScript | yarn lint:typescript |
| Stylelint | yarn lint:stylelint |
| Unit tests | yarn test:unit |
| Component tests | yarn test:components (after prod build) |
| E2E | yarn test:e2e (after prod build) |
Storybook: yarn --cwd .storybook-workspace install after root yarn.
See eslint-typescript.mdc, fantasia-dev-scoped-verify, fantasia-testing. Yarn 1.x: yarn check ≠ quality gate — full yarn testbatch:verify at commit; dev scoped gate while iterating.
Types
Shared types → types/. See types-folder.mdc.
