ppt-frontend

name	ppt-frontend
description	Navigate the React/pnpm frontend workspace — apps, shared packages, generated API client, Biome.
when_to_use	The plan touches anything under frontend/ — an app, a package, or the generated API client.
mode	both
capabilities	["C6"]
tags	["frontend"]

PPT Frontend

pnpm workspace at frontend/. ppt-web is a Vite + React SPA; reality-web is a Next.js 16 SSR app. Shared TS packages alongside. Biome for lint / format on most packages, ESLint per-app. Generated API clients live as separate packages.

When to invoke

Plan area is frontend, or Suggested approach references frontend/apps/** or frontend/packages/**.

What it gives you

• Apps & packages map
• pnpm filter syntax
• API-client regeneration loop (couples to ppt-typespec)
• The Vite vs Next.js split — different dev/build commands

Inputs

• A target app or package name

Apps and packages

frontend/apps/:

App	Port	Stack	Notes
ppt-web	3000	Vite + React (TS, vitest)	Property Management main web (SPA)
reality-web	3001	Next.js 16 (SSR, App Router)	Reality Portal public site
mobile	n/a	RN / Expo	React Native — see also ppt-mobile-native for the Kotlin native app

frontend/packages/:

Package	Purpose
api-client	Generated client for PPT API (regenerated by just generate-api-client)
reality-api-client	Generated client for Reality API (just generate-reality-api-client)
admin-ui	Admin/super-admin UI components
dev-panel	In-app dev/debug panel
screen-map	Screen-map generation tooling
shared	Cross-app types and utils
sitemap	Sitemap generation
ui-kit	Shared component library
vite-plugin-ppt-worktree	Worktree-aware vite plugin

Steps

1. Install deps (workspace-wide):

   cd frontend && pnpm install
   

2. Iterate on one app/package:

   # dev mode
   cd frontend && pnpm dev:ppt          # ppt-web (Vite) on :3000
   cd frontend && pnpm dev:reality      # reality-web (Next.js) on :3001
   cd frontend && pnpm dev:mobile       # RN/Expo
   
   # build / test one package
   cd frontend && pnpm -F <pkg> build
   cd frontend && pnpm -F <pkg> test
   cd frontend && pnpm -F <pkg> typecheck
   

3. Regenerate the API client after any backend API change:

   just generate-api                    # both clients
   just generate-api-client             # PPT only
   just generate-reality-api-client     # Reality only
   

   These wrap pnpm generate-api / pnpm generate-reality-api. They consume the spec emitted by ppt-typespec. If the contract changed, regenerate typespec → API spec → client in that order.
4. Lint / format before pushing:

   just check-frontend     # Biome lint + format check
   just fix-frontend       # auto-fix
   

5. Tests:

   just test-frontend                       # all
   cd frontend && pnpm -F @ppt/web test     # one app (package name, NOT dir name)
   # Other apps: @ppt/reality-web, @ppt/mobile. Packages: @ppt/api-client, @ppt/admin-ui, …
   

Deterministic verification

# 1. pnpm available
pnpm --version >/dev/null && echo OK
# expected: OK

# 2. workspace resolves
(cd frontend && pnpm -r exec true >/dev/null 2>&1) && echo OK
# expected: OK (works even before install — exec true is a noop)
# (subshell so the cwd stays at the repo root for the following checks)

# 3. expected apps present (paths from repo root)
for a in ppt-web reality-web mobile; do
  test -f "frontend/apps/$a/package.json" || { echo "missing app: $a"; exit 1; }
done
echo OK
# expected: OK

# 4. generated api-client package present
test -d frontend/packages/api-client && echo OK
# expected: OK

Smoke check (single command)

cd frontend && pnpm -r list --depth -1 --json >/dev/null

First run after a fresh clone needs pnpm install (downloads + builds native deps); the smoke check above only verifies the workspace resolves, not that node_modules is populated.

After-task verification

just check-frontend && just test-frontend

Cross-references

• ppt-typespec — regenerate clients after API contract change
• ppt-tests — pnpm filter syntax
• ppt-mobile-native — Kotlin app (separate from frontend/apps/mobile)