Recipe App — Frontend

A React single-page application for managing recipes and meal plans. Users can create, browse, edit, and comment on recipes; plan meals by assigning recipes to calendar days; and share meal plans with other users.

The backend lives in a separate repository (recipe-backend).

Stack: React 19 · TypeScript · Vite · Tailwind CSS v4 · React Router v7

For a full picture of the architecture, layers, and design decisions see docs/architecture.md.

---

Development

Prerequisites

• Node.js (check .nvmrc or use whatever is current LTS)
• The backend running locally (see recipe-backend)

First-time setup

npm install

.env.development is checked in and points BACKEND_URL at http://10.0.1.152:4000 (local backend). Adjust if your backend runs on a different address.

Day-to-day

npm run dev        # Start dev server at https://localhost:5173 (HTTPS required for ServiceWorker)
npm run test       # Run unit tests once
npm run test:watch # Run unit tests in watch mode
npm run lint       # ESLint check
npm run build      # Type-check + production build → dist/
npm run preview    # Serve the dist/ build locally

The dev server uses a self-signed certificate (@vitejs/plugin-basic-ssl). Accept the browser warning once per device. On mobile, you'll need to accept it at https://<your-LAN-IP>:5173.

API requests from the browser go to /api-proxy/* which Vite proxies to BACKEND_URL server-side — this avoids mixed-content blocks from the HTTPS dev server talking to an HTTP backend.

---

Environment files

File	Purpose
.env.development	Local dev — BACKEND_URL points to local backend, VITE_API_BASE is empty (proxy active)
.env.production	Production build — VITE_API_BASE points to the live backend

To override locally without touching the checked-in files, create .env.development.local (git-ignored).

---

Git workflow

• Work on a feature branch cut from stage; open PRs against stage — never main
• main is only updated by merging stage (releases)
• Branch names are bare kebab-case (recipe-print-view, not feature/recipe-print-view)
• Commit messages use conventional commits: feat, fix, refactor, docs, chore, test

Full rules in CLAUDE.md.

---

Project structure

src/
├── api/          # DTOs, resource classes, apiClient
├── auth/         # Session read/write, logout events
├── components/   # Pages and UI components
├── config/       # Layout constants, API config
├── contexts/     # Feature-scoped React contexts
├── hooks/        # Custom hooks
├── mappers/      # DTO ↔ Model conversion
├── models/       # View-layer TypeScript interfaces
├── utils/        # Pure utility functions
└── workers/      # ServiceWorker (auth-aware image caching)

See docs/architecture.md for the full layer model and component inventory.

---

Deployment

CI runs on Forgejo (.forgejo/workflows/). On push to stage it runs tests, builds, and deploys to the dev environment. Tagged releases deploy to production.

To trigger a production release: push a v* tag — the release workflow handles the rest.

---

Docs

Document	What's in it
docs/architecture.md	Full architecture, layer model, component inventory, design decisions
CLAUDE.md	Coding conventions, testing rules, git workflow — kept in sync with the codebase
docs/adr/	Architecture Decision Records for significant choices