env-web

name	env-web
description	Recipe for filling state/reference/ENV.md when the project is a web app (frontend or full-stack). Use when the project serves HTTP, has a dev server, or runs in a browser. Adjust package manager (pnpm/npm/yarn/bun) and test runner to match the project.
tools	["Read","Write","Bash"]

env-web — recipe for state/reference/ENV.md

Copy these blocks into state/reference/ENV.md and adjust commands. Replace pnpm with the package manager actually in use.

Profile

Profile: web

Bring up

• pnpm install --frozen-lockfile
• pnpm dev > .dev.log 2>&1 & then echo $! > .dev.pid (or use a process manager)
• Wait for ready: for i in 1..30; do curl -sf http://localhost:3000/health && break; Start-Sleep 1; done

Smoke (< 30s)

• pnpm typecheck
• curl -sf http://localhost:3000/health

Verify (canonical green-light)

• pnpm typecheck && pnpm test --run
  • non-interactive flags matter: --run for vitest, --watchAll=false for jest, --passWithNoTests if appropriate

E2E / instrumentation

• pnpm playwright test --reporter=line
• Headless by default. Trace artifacts in test-results/.

Capture logs

• Application logs: Get-Content .dev.log -Tail 200 (PowerShell) / tail -n 200 .dev.log
• Test logs: pnpm test --run --reporter=verbose 2>&1 | Tee-Object .test.log
• Browser console: Playwright captures these in trace; open via pnpm playwright show-trace test-results/<name>/trace.zip
• Network: Playwright trace, or run with --reporter=html and inspect playwright-report/
• Where logs land: .dev.log, .test.log, test-results/, playwright-report/

Tear down

• Stop dev server: Stop-Process -Id (Get-Content .dev.pid) / kill $(cat .dev.pid)
• Clean state: Remove-Item .next, dist, .turbo -Recurse -Force -ErrorAction SilentlyContinue

Devices / external services

• Browser: handled by Playwright (pnpm playwright install --with-deps once)
• DB / cache: if used, add docker compose up -d here

Known fragility

• Port 3000 collisions if a previous dev server didn't tear down — always check .dev.pid first
• Playwright on Windows may need pnpm playwright install --with-deps after node updates