grocery-app/docs/DEVELOPMENT.md

Development

Use this as the practical setup and verification guide. PROJECT_INSTRUCTIONS.md remains the source of truth for constraints.

Prerequisites

• Node.js 20.19+ or 22.12+ for the current Vite toolchain.
• npm.
• PostgreSQL client tools if running migration scripts (psql must be on PATH).
• Access to the external Postgres database through DATABASE_URL or backend DB variables.
• Docker is optional for local app containers.

Install

Run installs separately because this repo does not define npm workspaces.

npm ci
npm --prefix backend ci
npm --prefix frontend ci

Environment

• Copy backend/.env.example to backend/.env for backend runtime configuration.
• Copy frontend/.env.example to frontend/.env if the frontend needs non-default API or host settings.
• Do not commit real .env files.
• Root DB migration scripts read DATABASE_URL from the shell environment; they do not load backend/.env automatically.

Important variables:

Variable	Used by	Notes
DATABASE_URL	backend, root migration scripts	Preferred external Postgres connection string.
DB_USER, DB_PASS, DB_HOST, DB_PORT, DB_NAME	backend fallback	Used only when DATABASE_URL is absent.
JWT_SECRET	backend auth	Required for token/session-compatible auth paths.
ALLOWED_ORIGINS	backend CORS	Comma-separated allowed frontend origins.
SESSION_COOKIE_NAME, SESSION_TTL_DAYS	backend cookies	Optional; defaults are defined in code.
VITE_API_URL	frontend	Defaults to http://localhost:5000.
VITE_ALLOWED_HOSTS	Vite dev server	Comma-separated host allowlist.
PLAYWRIGHT_BASE_URL	Playwright	Defaults to http://localhost:3010.

Run Locally

Docker dev stack:

docker compose -f docker-compose.dev.yml up

Separate terminals:

npm run dev:backend
npm run dev:frontend

Default local endpoints:

• Backend: http://localhost:5000
• Frontend through Docker compose port mapping: http://localhost:3010
• Frontend direct Vite default: http://localhost:5173

Verification Commands

Root entry points:

npm test
npm run lint
npm run typecheck
npm run audit
npm run build:backend
npm run build:frontend
npm run build
npm run test:e2e

Migration checks:

npm run db:migrate:status
npm run db:migrate:verify
npm run db:migrate:stale:check

Do not run npm run db:migrate against a shared or production database unless that is the explicit operator task.

Common Troubleshooting

• DATABASE_URL is required: export/set DATABASE_URL in the shell before root migration commands.
• psql executable was not found in PATH: install PostgreSQL client tools.
• Frontend cannot reach backend: confirm VITE_API_URL, backend port 5000, and backend ALLOWED_ORIGINS.
• Playwright starts the frontend but API calls fail: start the backend separately or use the Docker dev stack.
• CORS blocked origin: add the exact frontend origin to ALLOWED_ORIGINS.

Before Finishing Work

• Re-read AGENTS.md and any relevant deeper doc.
• Run the smallest useful checks first.
• For API behavior changes, add/update Jest tests with negative cases.
• For user-facing UI behavior changes, add/update focused Playwright coverage.
• Summarize any command that failed, whether it appears pre-existing, and the unresolved risk.