a2c08aff45
All checks were successful
Build & Deploy Costco Grocery List / build (push) Successful in 1m36s
Build & Deploy Costco Grocery List / verify-images (push) Successful in 2s
Build & Deploy Costco Grocery List / deploy (push) Successful in 8s
Build & Deploy Costco Grocery List / notify (push) Successful in 0s
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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`; the e2e runner starts Vite on this URL. |
|
|
|
|
## Run Locally
|
|
Docker dev stack:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
Separate terminals:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
`npm run test:e2e` uses `frontend/scripts/run-playwright.mjs` to start Vite, run
|
|
Playwright, and shut Vite down cleanly. Pass Playwright flags after `--`, for
|
|
example `npm run test:e2e -- --reporter=list --workers=1`.
|
|
|
|
Migration checks:
|
|
|
|
```bash
|
|
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.
|