Child Gold Land — Frontend

Vue 3 + Vite + Pinia + TypeScript.

Requirements

• Node.js: ^22.18.0 or >=24.12.0 (package.json → engines)
• Pinned for local dev / CI: 22.18.0 (see .nvmrc)

nvm install 22.18.0
nvm use 22.18.0

Backend (sibling repo)

API is required for login and gameplay. Run Nest backend from ../backend-nest on port 3000 (separate Git repo: gold_land_server on Gitea).

Local development

npm ci
npm run dev

• App: http://localhost:5174 (vite.config.ts — strictPort: true)
• API: requests to /api/* are proxied to http://127.0.0.1:3000

Optional env: copy .env.example to .env.local if you need overrides (VITE_API_URL).

Demo account (when backend NODE_ENV=development): username demo, password 123456.

Scripts

Command	Description
npm run dev	Vite dev server (port 5174)
npm run build	vue-tsc + production build
npm run preview	Preview production build
npm run type-check	TypeScript check only
npm run test	Node unit tests (test/)
npm run test:e2e	Build backend + Playwright E2E (30 tests)
npm run test:e2e:ci	Playwright only (backend must already be built)
npm run test:e2e:install	playwright install chromium (+ OS deps on Linux: --with-deps)
npm run e2e:prepare	npm run build in backend (E2E_BACKEND_ROOT)
npm run ci:checkout-backend	Clone backend for CI layout (see E2E contract)

CI (Gitea Actions)

Workflow: .gitea/workflows/ci.yml (runs on push and pull_request when a Gitea act_runner is registered — not verified on get.feep.ir from this repo alone).

Jobs (this repository)

Job	Steps (same as local)
unit	npm ci → npm run test → npm run type-check → npm run build
e2e	checkout frontend → clone pinned backend → npm ci (both) → e2e:prepare → playwright install chromium --with-deps → npm run test:e2e:ci

• Node: 22.18.0 (explicit in workflow)
• Cache: npm cache via actions/setup-node (optional; job still passes without cache)
• Timeouts: unit 25 min, e2e 45 min
• Failure artifacts: playwright-report/, test-results/ (no tokens, no production DB)
• Cleanup: npm run e2e:cleanup runs always() after E2E

Local equivalent (unit checks)

npm ci
npm run test
npm run type-check
npm run build

Two-repo E2E contract

Item	Value
Contract file	e2e/backend.contract.json
Default backend URL	https://get.feep.ir/gold_land/gold_land_server.git
Default ref	main (override for reproducibility)
Checkout path (CI)	backend-nest/ under frontend workspace
Backend build	npm run build in that tree (e2e:prepare)
E2E backend port	3010 (E2E_BACKEND_PORT)
E2E frontend port	5190 (E2E_FRONTEND_PORT)
Readiness	GET http://127.0.0.1:3010/health
Temp DB	SQLite under OS temp (scripts/e2e-backend.mjs) — never data/app.db

Pin backend version in CI (required for e2e job): set repository variable E2E_BACKEND_REF to a commit SHA (or immutable tag). There is no silent fallback to main.

Local sibling layout (no clone):

$env:E2E_BACKEND_ROOT = "E:\path\to\backend-nest"   # optional; default is ../backend-nest
npm run test:e2e

Local fallback when Playwright Chromium CDN fails: $env:PLAYWRIGHT_CHROME_CHANNEL = "chrome" (system Chrome). CI must not rely on this — use npx playwright install chromium --with-deps.

Secrets (names only — never commit values)

Name	Purpose
E2E_BACKEND_CHECKOUT_TOKEN	Read access to private gold_land_server for git clone in E2E job

If the backend repo is public, clone may work without a token. If clone fails, the e2e job fails; unit still runs.

Runner prerequisites (Linux, e.g. ubuntu-latest label)

• Node 22.18.0
• Git
• Build toolchain for better-sqlite3 (backend dependency): build-essential, python3 (Playwright --with-deps installs browser OS libs; backend npm ci still needs native compile on Linux)
• Sufficient disk for node_modules × 2 + Chromium

Not yet verified on a real runner

• Gitea Actions enabled and act_runner online for gold_land/gold_land_user
• E2E job with private backend clone + E2E_BACKEND_CHECKOUT_TOKEN
• vars.E2E_BACKEND_REF / gitea.run_id in workflow expressions (Gitea ≥ 1.21; github.* aliases may apply)

Optional: start backend + frontend (Windows)

pwsh -File ..\backend-nest\scripts\dev-local-stack.ps1

Sibling folder layout: frontend + backend-nest.

Docker / trial deploy

docker-compose.yml builds frontend + backend for a trial stack (nginx + Nest + SQLite volume).

See docs/DEPLOY-TRIAL.md for architecture, placeholders, HTTPS notes, backup, health, and rollback.

Local day-to-day dev usually uses npm run dev + backend npm run dev or npm run start.

Project status doc

A workspace-level overview may exist at ../docs/project-status.md when both repos share a parent folder. That file is not part of this Git repo.