121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
# Frontend Infrastructure Hardening Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Stabilize frontend infrastructure and tooling so local development, contract freshness, and mock-based workflows are deterministic and do not rely on temporary compatibility layers.
|
|
|
|
**Architecture:** This feature is a small set of related infrastructure follow-ups executed in a controlled order: mock-mode docs and wiring, env validation, tooling consistency, and contract freshness. Each step should leave the project in a working state and avoid changing user-facing runtime behavior except where the infrastructure itself must be activated.
|
|
|
|
**Tech Stack:** Vite, MSW, Zod, Biome/ESLint, OpenAPI-generated types, existing frontend tooling scripts.
|
|
|
|
---
|
|
|
|
### Task 1: Browser mock mode wiring
|
|
|
|
**Files:**
|
|
- Create/Modify: `apps/frontend/mocks/browser.ts`
|
|
- Modify: `apps/frontend/public/mockServiceWorker.js`
|
|
- Modify: `apps/frontend/src/main.tsx`
|
|
- Modify: `apps/frontend/src/shared/config/env.ts`
|
|
- Modify: `apps/docs/docs/development/commands.md`
|
|
- Modify: `apps/docs/docs/frontend/overview.md`
|
|
|
|
- [ ] **Step 1: Add a browser MSW entry that reuses existing handlers**
|
|
|
|
Ensure the browser worker uses the existing `apps/frontend/mocks/handlers.ts` instead of duplicating request logic.
|
|
|
|
- [ ] **Step 2: Gate worker startup behind `VITE_API_MOCK`**
|
|
|
|
Hook the browser mock startup into `main.tsx` so it activates only when the env flag explicitly asks for it.
|
|
|
|
- [ ] **Step 3: Document the mock mode behavior**
|
|
|
|
Document the developer-facing rule: mock mode is opt-in, backend-free dev is supported, and the default path still uses the real API.
|
|
|
|
### Task 2: Env validation
|
|
|
|
**Files:**
|
|
- Modify: `apps/frontend/src/shared/config/env.ts`
|
|
- Modify: `apps/frontend/src/main.tsx`
|
|
- Test: any existing frontend startup/env tests, if present
|
|
|
|
- [ ] **Step 1: Define the runtime env schema**
|
|
|
|
Add a Zod schema for required `VITE_*` variables and keep optional values explicit.
|
|
|
|
- [ ] **Step 2: Fail fast on invalid env**
|
|
|
|
Call validation before app render so invalid configuration is visible at startup instead of failing later in a component or query path.
|
|
|
|
- [ ] **Step 3: Verify startup messaging**
|
|
|
|
Make sure the error path explains what is missing or invalid without leaking secrets.
|
|
|
|
### Task 3: Tooling consistency
|
|
|
|
**Files:**
|
|
- Modify: `apps/frontend/package.json`
|
|
- Modify: `apps/frontend/.eslintrc.cjs` or `apps/frontend/biome.json` if the project already has a replacement config
|
|
- Modify: `.gitea/workflows/ci.yml` only if the current tooling commands need to be aligned
|
|
- Modify: `apps/docs/docs/development/commands.md`
|
|
|
|
- [ ] **Step 1: Verify the command set matches the current toolchain**
|
|
|
|
Keep `lint`, `test`, `build`, and `codegen` aligned with the real frontend structure and remove stale command references.
|
|
|
|
- [ ] **Step 2: Align lint/format docs with reality**
|
|
|
|
Update documentation so it describes the actual commands developers run today, not an earlier migration stage.
|
|
|
|
- [ ] **Step 3: Confirm no stale tooling references remain**
|
|
|
|
Remove or rewrite mentions of dead scripts, obsolete shims, or incorrect setup instructions.
|
|
|
|
### Task 4: Contract freshness
|
|
|
|
**Files:**
|
|
- Modify: `apps/frontend/src/shared/api/index.ts`
|
|
- Modify: `apps/frontend/src/shared/api/types.ts` only through codegen, not manual edits
|
|
- Modify: the specific frontend entity API files that still depend on stale wrapper assumptions
|
|
- Modify: `apps/docs/docs/frontend/api-client.md`
|
|
- Modify: `apps/docs/docs/frontend/overview.md`
|
|
|
|
- [ ] **Step 1: Reconcile the frontend contract entrypoints**
|
|
|
|
Ensure the shared API surface points to the actual generated contract types and current public API entrypoints.
|
|
|
|
- [ ] **Step 2: Remove stale contract wording from docs**
|
|
|
|
Document the current source of truth for API types and avoid references to temporary compatibility layers.
|
|
|
|
- [ ] **Step 3: Verify generated types are treated as generated**
|
|
|
|
Make sure the plan keeps `types.ts` as generated output and avoids manual editing patterns.
|
|
|
|
### Task 5: Verification
|
|
|
|
**Files:**
|
|
- Read: changed docs and frontend tooling files
|
|
|
|
- [ ] **Step 1: Run the targeted frontend checks**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm run lint -w apps/frontend
|
|
npm run test -w apps/frontend
|
|
npm run build -w apps/frontend
|
|
```
|
|
|
|
Expected: all three commands pass after the infra hardening changes land.
|
|
|
|
- [ ] **Step 2: Check mock mode manually**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
VITE_API_MOCK=true npm run dev -w apps/frontend
|
|
```
|
|
|
|
Expected: frontend starts with browser MSW available and does not require the backend for the basic local flow.
|