From 6022929551ace6ab421f13afa5ee81e323c4fbed Mon Sep 17 00:00:00 2001 From: Matiss Janis Aboltins Date: Fri, 27 Feb 2026 20:38:37 +0000 Subject: [PATCH] [Cursor] Development environment setup (#7088) * [AI] Add Cursor Cloud specific instructions to AGENTS.md Co-authored-by: Matiss Janis Aboltins * [autofix.ci] apply automated fixes * Add release notes for PR #7088 * [AI] Fix Node.js minimum version requirement in AGENTS.md (#7089) * [AI] Fix outdated Node.js version requirement in Build Failures section Co-authored-by: Matiss Janis Aboltins * [AI] Add test budget tip to Cursor Cloud instructions Co-authored-by: Matiss Janis Aboltins --------- Co-authored-by: Cursor Agent Co-authored-by: Matiss Janis Aboltins Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> --- AGENTS.md | 41 ++++++++++++++++++++++++++++++++-- upcoming-release-notes/7088.md | 6 +++++ 2 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 upcoming-release-notes/7088.md diff --git a/AGENTS.md b/AGENTS.md index a9a736b4b1..f9f5c62071 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -529,7 +529,7 @@ Icons in `packages/component-library/src/icons/` are auto-generated. Don't manua 1. Clean build artifacts: `rm -rf packages/*/dist packages/*/lib-dist packages/*/build` 2. Reinstall dependencies: `yarn install` -3. Check Node.js version (requires >=20) +3. Check Node.js version (requires >=22) 4. Check Yarn version (requires ^4.9.1) ## Testing Patterns @@ -619,7 +619,7 @@ yarn install:server ## Environment Requirements -- **Node.js**: >=20 +- **Node.js**: >=22 - **Yarn**: ^4.9.1 (managed by packageManager field) - **Browser Targets**: Electron >= 35.0, modern browsers (see browserslist) @@ -632,3 +632,40 @@ The codebase is actively being migrated: - **React.\* → Named Imports**: Legacy React.\* patterns being removed When working with older code, follow the newer patterns described in this guide. + +## Cursor Cloud specific instructions + +### Services overview + +| Service | Command | Port | Required | +| ------------------- | ----------------------- | ---- | ----------------------------- | +| Web Frontend (Vite) | `yarn start` | 3001 | Yes | +| Sync Server | `yarn start:server-dev` | 5006 | Optional (sync features only) | + +All storage is **SQLite** (file-based via `better-sqlite3`). No external databases or services are needed. + +### Running the app + +- `yarn start` builds the plugins-service worker, loot-core browser backend, and starts the Vite dev server on port **3001**. +- `yarn start:server-dev` starts both the sync server (port 5006) and the web frontend together. +- The Vite HMR dev server serves many unbundled modules. In constrained environments, the browser may hit `ERR_INSUFFICIENT_RESOURCES`. If that happens, use `yarn build:browser` followed by serving the built output from `packages/desktop-client/build/` with proper COOP/COEP headers (`Cross-Origin-Opener-Policy: same-origin`, `Cross-Origin-Embedder-Policy: require-corp`). + +### Lint, test, typecheck + +Standard commands documented in `package.json` scripts and the Quick Start section above: + +- `yarn lint` / `yarn lint:fix` (uses oxlint + oxfmt) +- `yarn test` (lage across all workspaces) +- `yarn typecheck` (tsc + lage typecheck) + +### Testing and previewing the app + +When running the app for manual testing or demos, use **"View demo"** on the initial setup screen (after selecting "Don't use a server"). This creates a test budget pre-populated with realistic sample data (accounts, transactions, categories, and budgeted amounts), which is far more useful than starting with an empty budget. + +### Gotchas + +- The `engines` field requires **Node.js >=22** and **Yarn ^4.9.1**. The `.nvmrc` specifies `v22/*`. +- Pre-commit hook runs `lint-staged` (oxfmt + oxlint) via Husky. Run `yarn prepare` once after install to set up hooks. +- Lage caches test results in `.lage/`. If tests behave unexpectedly, clear with `rm -rf .lage`. +- Native modules (`better-sqlite3`, `bcrypt`) require build tools (`gcc`, `make`, `python3`). These are pre-installed in the Cloud VM. +- All yarn commands must be run from the repository root, never from child workspaces. diff --git a/upcoming-release-notes/7088.md b/upcoming-release-notes/7088.md new file mode 100644 index 0000000000..b70031d4f5 --- /dev/null +++ b/upcoming-release-notes/7088.md @@ -0,0 +1,6 @@ +--- +category: Maintenance +authors: [MatissJanis] +--- + +Add Cursor Cloud setup instructions and troubleshooting tips to AGENTS.md documentation.