@zigrivers/scaffold 3.5.3 → 3.7.0

package/content/knowledge/web-app/web-app-deployment-workflow.md

@@ -0,0 +1,143 @@
+---
+name: web-app-deployment-workflow
+description: Preview deploys per PR, staging environments, deployment branches, CI/CD pipeline stages, rollback strategies, and canary deployments
+topics: [web-app, deployment, ci-cd, staging, preview, rollback, canary]
+---
+
+A mature deployment workflow transforms deployment from a risky, manual event into a routine, automated step. The goal is to make every merge to main automatically and safely deliverable to production, with fast rollback when something goes wrong. The cost of building this infrastructure up front is trivially small compared to the cost of a major incident caused by a manual deploy process.
+
+## Summary
+
+A mature deployment workflow makes every merge to main automatically deliverable with fast rollback. Every PR gets a preview deploy. CI/CD runs lint, typecheck, test, and build in fail-fast order. Test rollback procedures quarterly. For high-traffic apps, use canary deployments with explicit rollback criteria.
+
+## Deep Guidance
+
+### Preview Deploys Per PR
+
+Every pull request should get its own preview deployment — a fully functional URL that reviewers and QA can use to verify behavior before merging. This is the single highest-ROI practice in modern web deployment:
+
+- **Vercel, Netlify, Railway**: Automatically create preview deploys on PR open/push. Zero configuration for most frameworks.
+- **Custom CI**: Build and deploy to a path-based preview URL (`preview/<pr-number>/`) or a subdomain. Tear down on PR close.
+
+Preview deploys must use isolated environment variables (dev database, dev third-party API keys). Never point a preview deploy at a production database.
+
+### Deployment Branches
+
+Establish a clear branch-to-environment mapping and document it in the repo:
+
+| Branch | Environment | Deploys |
+|--------|-------------|---------|
+| `main` | Production | Automatic on merge |
+| `staging` | Staging | Automatic on merge |
+| `feature/*`, `fix/*` | Preview | Automatic on PR push |
+
+Avoid long-lived branches other than `main` and optionally `staging`. Feature branches merge to `main` via PR. `main` deploys to production. This is the simplest model that works.
+
+If you have a separate `staging` branch: keep it in sync with `main` via regular merges. Staging branches that lag `main` by weeks create false confidence and painful integration surprises.
+
+### CI/CD Pipeline Stages
+
+Every push to a branch should run a pipeline in this order (fast-to-slow, fail-fast):
+
+1. **Install dependencies** (cached; skip if lockfile unchanged)
+2. **Lint** — ESLint, Prettier check (fail fast; ~30 seconds)
+3. **Typecheck** — `tsc --noEmit` (fail fast; ~60 seconds)
+4. **Unit tests** — Vitest/Jest with coverage threshold (1–3 minutes)
+5. **Build** — Production build to verify no build errors (2–5 minutes)
+6. **E2E tests** (optional, on main/staging only) — Playwright or Cypress against preview deploy (5–15 minutes)
+7. **Deploy** — Only if all above pass
+
+Do not run all tests on every PR if the test suite is slow. Use test impact analysis (run only tests related to changed files) or split E2E tests to a separate workflow that runs on merge to `main`.
+
+### Rollback Strategies
+
+Every deployment system must have a tested rollback procedure. "We can just revert the commit and redeploy" is not a rollback strategy — that takes 5+ minutes and requires a developer to execute it under pressure.
+
+- **Vercel/Netlify**: One-click rollback to any previous deployment in the dashboard. Target: under 30 seconds to rollback.
+- **Custom infrastructure**: Maintain the previous two deployment artifacts. Rollback = swap the active artifact. Use blue-green or immutable deployment patterns (see below).
+- **Database migrations**: Rollback is the hard part. Write migrations that are forward-compatible (additive only). Keep destructive changes separate, deployed only after the new code is stable. Use a migration tool that tracks state (Prisma, Flyway, Liquibase).
+
+Test the rollback procedure at least quarterly. A rollback you have never practiced will fail in an incident.
+
+### Canary Deployments
+
+For high-traffic production apps, deploy changes to a small percentage of traffic before full rollout:
+
+- Route 5% of requests to the new version, 95% to the old
+- Monitor error rates, latency, and business metrics for 15–30 minutes
+- Gradually increase the percentage or roll back if metrics degrade
+
+Canary deployments require infrastructure support: feature flag services (LaunchDarkly, Unleash), traffic splitting at the load balancer (AWS ALB weighted routing, Cloudflare Workers), or platform-level support (Vercel edge middleware). Do not implement canaries manually — use the platform's built-in mechanism.
+
+### CI/CD Pipeline Template (GitHub Actions)
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run test -- --coverage
+      - run: npm run build
+
+  deploy-preview:
+    needs: quality
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci && npm run build
+      - name: Deploy preview
+        run: npx vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}
+```
+
+### Deployment Environment Variables
+
+Separate environment variables by tier and manage them securely:
+
+- **Local**: `.env.local` (gitignored, developer-managed)
+- **Preview**: Vercel/Netlify project environment variables, marked "Preview" tier; use dev API keys only
+- **Staging**: Staging-specific secrets in GitHub Actions or your secrets manager
+- **Production**: Production secrets never visible to developers; managed by infra/ops
+
+Audit who has access to production secrets quarterly. Rotate API keys and tokens on team member offboarding without exception.
+
+### Defining "Deployment Complete"
+
+A deployment is not complete when the deploy command exits. It is complete when:
+
+1. The new version is serving traffic (health check passes)
+2. Error rate is not elevated above baseline
+3. Response latency p95 is not elevated above baseline
+4. At least one synthetic monitor has confirmed the critical user journey works
+
+Automate this check in your deploy pipeline. Do not send "deploy succeeded" notifications until you have validated real traffic behavior.
+
+### Zero-Downtime Deployments
+
+For apps that cannot tolerate downtime:
+
+- **Rolling deployments**: Bring up new instances, drain old instances. Requires stateless services (no in-memory session storage).
+- **Blue-green deployments**: Run two identical environments (blue = current, green = new). Switch traffic at the load balancer level. Old environment stays up as instant rollback target.
+- **Feature flags**: Deploy code to production without enabling it. Enable via flag without a deployment. Fastest and most controllable rollout mechanism.
+
+For stateful workloads (databases, file storage): always plan the data migration before the code migration. Code deploys are reversible; bad data migrations often are not.

package/content/knowledge/web-app/web-app-deployment.md

@@ -0,0 +1,134 @@
+---
+name: web-app-deployment
+description: Static CDN hosting, serverless platforms, container deployments, edge runtimes, long-running servers, and blue-green deploy patterns for web apps
+topics: [web-app, deployment, vercel, netlify, aws, docker, cloudflare, serverless, containers]
+---
+
+Deployment platform selection determines your app's operational cost, performance ceiling, and scaling characteristics. Each platform has a different cost model, latency profile, and runtime constraint. Choose based on your app's rendering strategy, traffic patterns, and team's operational expertise — not on what is fashionable.
+
+## Summary
+
+Web app deployment platforms range from static CDN hosting (cheapest, fastest TTFB) through serverless (pay-per-invocation, cold start concerns), containers (persistent connections, custom runtimes), edge functions (global low-latency transformations), to long-running servers (WebSockets, background jobs). Choose based on rendering strategy, traffic patterns, and operational expertise.
+
+## Deep Guidance
+
+### Static Hosting (CDN)
+
+For SSG applications with no server-side rendering at request time:
+
+- **Best platforms**: Cloudflare Pages, Netlify, Vercel (static tier), AWS S3 + CloudFront, GitHub Pages
+- **Cost**: Near zero for low-to-medium traffic; CDN egress costs at very high traffic
+- **Performance**: Best possible — globally distributed, no cold starts, ~50 ms TTFB from any major city
+- **Limitations**: No request-time server logic, no secrets at request time, data freshness = deploy frequency
+
+Configure aggressive caching headers. Static assets (hashed filenames) get `Cache-Control: immutable, max-age=31536000`. HTML pages get `Cache-Control: no-cache` (validated on every request, served from cache when fresh).
+
+### Serverless (Vercel, Netlify, AWS Lambda)
+
+For SSR apps or API routes that need server logic at request time without managing servers:
+
+- **Best platforms**: Vercel (Next.js-native), Netlify Functions, AWS Lambda + API Gateway, Cloudflare Pages Functions
+- **Cost model**: Pay per invocation and compute time. Typically very cheap at low traffic, can become expensive at sustained high traffic vs. a long-running server.
+- **Cold starts**: The primary performance concern. Lambda cold starts: 100–500 ms (Node.js), 1–3 seconds (container-based). Vercel/Netlify Edge Functions: 0 ms (V8 isolates, not containers).
+- **Limitations**: Execution time limits (Vercel: 10–300 seconds depending on plan; Lambda: 15 minutes max), no persistent memory between invocations, no long-lived connections
+
+Minimize cold start impact: keep bundles small (Lambda-specific: prefer ESM + tree-shaking over CommonJS), use Provisioned Concurrency for latency-critical endpoints, or migrate latency-sensitive APIs to edge functions.
+
+### Container (Docker, AWS ECS/Fargate, Google Cloud Run)
+
+For apps that need more control than serverless, persistent connections, or custom runtime environments:
+
+- **Best platforms**: AWS ECS/Fargate, Google Cloud Run, Azure Container Apps, Railway, Fly.io, self-managed Kubernetes
+- **Cost model**: Per-container-hour (Fargate) or per-request with scale-to-zero (Cloud Run). More expensive than serverless at low traffic, cheaper at sustained high traffic.
+- **Benefits over serverless**: No cold starts with min replicas > 0, persistent WebSocket connections, custom binaries/runtimes, larger memory limits
+- **Operational overhead**: You manage container definitions, health checks, and scaling policies
+
+Use multi-stage Docker builds to minimize image size. Target images under 200 MB:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package.json ./
+RUN npm ci --omit=dev
+USER node
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Edge (Cloudflare Workers, Vercel Edge Functions)
+
+For global, low-latency request processing with simple logic:
+
+- **Runtime**: V8 isolates (not Node.js). Fast startup (~0 ms), runs at 300+ edge locations globally, ~1–5 ms TTFB worldwide.
+- **Use cases**: Auth token validation, A/B testing, geo-routing, request rewriting, rate limiting, personalized cache headers
+- **Limitations**: No Node.js built-ins (`fs`, `crypto` partially available, `child_process` unavailable), no SQLite, execution time limits (50 ms CPU time on Cloudflare free tier), no persistent file system
+- **Data access**: Use edge-native databases: Cloudflare D1 (SQLite), Cloudflare KV, Upstash Redis, PlanetScale edge
+
+Never put complex business logic in edge functions. Their value is speed and global distribution for request/response transformations, not application logic.
+
+### Long-Running Server (Express, Fastify, Node.js HTTP)
+
+For apps that need WebSockets, background jobs, or full control over the request lifecycle:
+
+- **Best platforms**: AWS EC2 + ALB, Fly.io, Railway, DigitalOcean Droplets, Hetzner (cost-efficient)
+- **When to choose**: Real-time features (WebSockets, SSE), background workers, long-running database transactions, legacy apps that cannot be adapted to serverless constraints
+
+### Blue-Green Deployments
+
+Blue-green deployments eliminate downtime and reduce rollback time to seconds:
+
+1. **Blue** = current production (100% of traffic)
+2. **Green** = new version (deployed but receiving 0% of traffic)
+3. Run smoke tests against the green environment
+4. Switch the load balancer to route 100% of traffic to green
+5. Monitor for 5–15 minutes
+6. If healthy: decommission blue. If unhealthy: switch back to blue (rollback complete in < 30 seconds)
+
+Requirements: stateless app servers (session data in Redis/DB, not in-memory), database schema changes must be backward-compatible with both versions simultaneously.
+
+### Platform Selection Decision Matrix
+
+| Criteria | Static CDN | Serverless | Container | Edge | Long-Running |
+|----------|-----------|------------|-----------|------|--------------|
+| SSG only | Best | Overkill | Overkill | Good | Overkill |
+| SSR with SEO | — | Best | Good | Good | Good |
+| Real-time (WebSocket) | No | No | Best | No | Best |
+| Low traffic / cost | Best | Best | Expensive | Best | Expensive |
+| High sustained traffic | Best | Expensive | Best | Best | Best |
+| Cold start sensitive | N/A | Problem | Solved | Solved | Solved |
+| Ops complexity | Lowest | Low | Medium | Low | High |
+
+### Health Checks and Readiness Probes
+
+Every deployed service must expose health endpoints:
+
+```typescript
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Check critical dependencies
+    await db.query("SELECT 1");
+    return Response.json({ status: "healthy", version: process.env.npm_package_version });
+  } catch (error) {
+    return Response.json({ status: "unhealthy", error: String(error) }, { status: 503 });
+  }
+}
+```
+
+Configure your load balancer or container orchestrator to route traffic only to healthy instances. Health check failure should trigger automatic rollback in your deployment pipeline.
+
+### Cost Optimization
+
+- Use serverless for variable or low traffic; switch to containers once monthly serverless cost exceeds 2–3 baseline container instances
+- CDN cache hit rate should be above 90% for SSG content — if it is not, investigate cache-busting headers
+- Set spending alerts at 50% and 100% of monthly budget on cloud providers — auto-remediation (scale down) if the alert fires on unexpected traffic

package/content/knowledge/web-app/web-app-design-system.md

@@ -0,0 +1,158 @@
+---
+name: web-app-design-system
+description: Responsive token systems, dark/light mode, component library patterns, and CSS methodology selection for web applications
+topics: [web-app, design-system, css, tokens, dark-mode, responsive]
+---
+
+A design system is the contract between design and engineering. Without one, components drift, spacing is inconsistent, and every engineer makes independent decisions about color, typography, and layout. A well-structured token system makes that contract explicit, machine-enforceable, and refactorable — changing a spacing scale or switching a brand color becomes a one-line edit rather than a codebase-wide search-and-replace.
+
+## Summary
+
+A design system encodes design decisions as tokens at three tiers: primitive (raw values), semantic (intent-based aliases), and component-scoped overrides. Support dark/light mode via CSS custom properties with both `prefers-color-scheme` and explicit `data-theme` toggle. Commit to a consistent breakpoint scale and CSS methodology. Use headless component libraries for accessible behavior with full visual control.
+
+## Deep Guidance
+
+### Token Architecture
+
+Design tokens are the atoms of a design system. They encode decisions — not values — at three tiers:
+
+1. **Primitive tokens** — Raw values with no semantic meaning: `--color-blue-500: #3b82f6`, `--spacing-4: 16px`, `--font-size-lg: 1.125rem`. Never use primitive tokens directly in components.
+
+2. **Semantic tokens** — Intent-based aliases of primitives: `--color-interactive: var(--color-blue-500)`, `--space-component-padding: var(--spacing-4)`. Components consume semantic tokens.
+
+3. **Component tokens** — Component-scoped overrides: `--button-background: var(--color-interactive)`. Allows per-component theming without touching semantic tokens.
+
+Spacing, typography, and breakpoints belong in this hierarchy. A spacing scale (4/8/12/16/24/32/48/64px) enforced via tokens prevents the "just add a margin-top: 11px" habit that destroys visual rhythm.
+
+### Dark/Light Mode
+
+Use CSS custom properties with `prefers-color-scheme` and an explicit `data-theme` attribute override:
+
+```css
+/* Primitive layer */
+:root {
+  --color-neutral-0: #ffffff;
+  --color-neutral-900: #111827;
+}
+
+/* Semantic layer — light mode defaults */
+:root {
+  --color-surface: var(--color-neutral-0);
+  --color-text-primary: var(--color-neutral-900);
+}
+
+/* Dark mode via media query */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-surface: var(--color-neutral-900);
+    --color-text-primary: var(--color-neutral-0);
+  }
+}
+
+/* Manual override via JS toggle */
+[data-theme="dark"] {
+  --color-surface: var(--color-neutral-900);
+  --color-text-primary: var(--color-neutral-0);
+}
+```
+
+Always support both mechanisms: `prefers-color-scheme` for first-visit experience, `data-theme` for user preference stored in `localStorage`.
+
+### CSS Methodology Selection
+
+| Approach | Best For | Trade-offs |
+|---|---|---|
+| Utility-first (Tailwind) | Rapid iteration, small teams, consistent constraints | Verbose JSX, limited custom design expression |
+| CSS Modules | Scoped styles with full CSS power, no runtime cost | Manual naming, no global token enforcement |
+| CSS-in-JS (Emotion, styled-components) | Dynamic theming, colocation, TypeScript safety | Runtime cost, hydration complexity in SSR |
+| Zero-runtime (Vanilla Extract, Linaria) | SSR-safe, type-safe tokens, no runtime overhead | Build-time complexity, less dynamic |
+
+For most production web apps, the recommendation is: **Tailwind + CSS custom properties** for utility-heavy UIs, or **CSS Modules + tokens** for design-system-first projects where designers own the token layer.
+
+### Responsive Breakpoints
+
+Commit to a consistent breakpoint scale and never deviate:
+
+```css
+/* Mobile-first breakpoints */
+--bp-sm: 640px;   /* Large phones */
+--bp-md: 768px;   /* Tablets */
+--bp-lg: 1024px;  /* Small desktops */
+--bp-xl: 1280px;  /* Large desktops */
+--bp-2xl: 1536px; /* Wide screens */
+```
+
+Use `min-width` queries exclusively (mobile-first). Avoid magic numbers in media queries — always reference the token scale.
+
+### Component Library Patterns
+
+A component library is the implementation layer of the design system. Key architectural decisions:
+
+**Compound components over prop explosion:**
+
+```tsx
+// BAD: Props explode as requirements grow
+<Select
+  label="Country"
+  options={countries}
+  placeholder="Select..."
+  isSearchable
+  isClearable
+  isMulti
+  maxSelectedItems={3}
+/>
+
+// GOOD: Compound pattern — composable, extensible
+<Select value={value} onChange={setValue}>
+  <Select.Trigger>
+    <Select.Value placeholder="Select country..." />
+  </Select.Trigger>
+  <Select.Content>
+    <Select.Search />
+    {countries.map(c => (
+      <Select.Item key={c.code} value={c.code}>{c.name}</Select.Item>
+    ))}
+  </Select.Content>
+</Select>
+```
+
+**Headless components for styling flexibility:**
+Use Radix UI, Headless UI, or React Aria as the unstyled behavior layer. Wire your token system on top. This gives accessible keyboard navigation and ARIA semantics for free while preserving full visual control.
+
+**Token enforcement via linting:**
+Use `stylelint-no-invalid-hex` and custom Stylelint rules (or ESLint for CSS-in-JS) to reject hardcoded color values not referencing a token. Automate this in CI.
+
+### Typography Scale
+
+Build a modular type scale with explicit roles:
+
+```css
+:root {
+  /* Scale steps — use a modular scale ratio (1.25 or 1.333) */
+  --text-xs: 0.75rem;    /* 12px — labels, captions */
+  --text-sm: 0.875rem;   /* 14px — body secondary */
+  --text-base: 1rem;     /* 16px — body primary */
+  --text-lg: 1.125rem;   /* 18px — subheadings */
+  --text-xl: 1.25rem;    /* 20px — section headings */
+  --text-2xl: 1.5rem;    /* 24px — page headings */
+  --text-3xl: 1.875rem;  /* 30px — hero headings */
+
+  /* Line heights tied to text size for proper vertical rhythm */
+  --leading-tight: 1.25;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.75;
+}
+```
+
+Never use pixel values for font sizes in component code — only reference scale tokens. This ensures user font size preferences (browser zoom, accessibility settings) are respected.
+
+### Design Token Pipeline
+
+For teams with a Figma design system, automate the token pipeline:
+
+1. Designers export tokens from Figma using the Tokens Studio plugin as a JSON file
+2. CI runs a token transformer (Style Dictionary) that converts JSON to CSS custom properties, TypeScript constants, and platform-specific formats
+3. The generated files are committed to the repository and reviewed in PRs
+4. Token changes are flagged in design review before code review
+
+This makes "design changed the brand blue" a designer-owned PR rather than an engineering ticket.

package/content/knowledge/web-app/web-app-dev-environment.md

@@ -0,0 +1,173 @@
+---
+name: web-app-dev-environment
+description: Dev server configuration, HMR setup, API proxy, environment variables, Docker for local services, and browser devtools for web app development
+topics: [web-app, dev-environment, vite, webpack, hmr, docker, debugging]
+---
+
+A fast, reliable local development environment is a force multiplier for the entire team. The goal is sub-second feedback loops for code changes and zero friction getting from a fresh checkout to a running app. Every minute spent fighting the dev environment is a minute not spent building the product.
+
+## Summary
+
+A fast web app dev environment targets sub-second feedback loops with HMR and zero-friction onboarding. Use Vite for new projects (or the framework's built-in server for Next.js). Configure an API proxy to avoid CORS issues. Validate environment variables at startup with a schema. Run local dependencies in Docker Compose.
+
+## Deep Guidance
+
+### Dev Server Choice: Vite vs webpack
+
+For new projects in 2024 and beyond, use **Vite** unless you have a specific reason not to:
+
+- **Vite**: Native ESM dev server, near-instant startup regardless of project size, esbuild-powered transforms (10–100x faster than Babel), first-class support for React, Vue, Svelte, and TypeScript out of the box.
+- **webpack (via Create React App, Next.js with webpack, or custom)**: Slower cold starts and HMR, but battle-tested and required by some frameworks. Next.js 13+ defaults to Turbopack (Rust-based, approaching Vite speed).
+
+If you are on Next.js, you get the dev server bundled with the framework. Do not fight the framework's built-in tooling — configure it via `next.config.ts`, not by ejecting or customizing webpack directly unless absolutely necessary.
+
+### HMR Configuration
+
+Hot Module Replacement keeps the page live-updating without full reloads. Ensure it is working correctly:
+
+- With Vite: HMR works out of the box. If it stops working after upgrading, check `server.hmr` in `vite.config.ts`. Common issue: HMR fails silently when a module has a circular dependency.
+- With React: Install `@vitejs/plugin-react` (uses Babel with Fast Refresh) or `@vitejs/plugin-react-swc` (uses SWC, 3–5x faster). Fast Refresh preserves component state on save — test that it works for your components.
+- Watch for HMR performance degradation in large projects: if HMR is slow, profile with `vite --debug hmr`. The usual cause is a large shared module being invalidated on every change.
+
+### API Proxy Configuration
+
+During development, your app's origin is `localhost:3000` but your API backend is `localhost:8000`. Avoid CORS issues and hardcoded localhost URLs by configuring a dev proxy:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      "/api": {
+        target: "http://localhost:8000",
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ""),
+      },
+    },
+  },
+});
+```
+
+This means your frontend code always calls `/api/users` and the proxy handles routing to the backend. The same relative URL works in production when the API is behind the same domain. Never hardcode `http://localhost:8000` in application code.
+
+### Environment Variables
+
+Use `.env` files for environment-specific configuration. Establish clear conventions:
+
+- `.env.example` — committed, documents all variables with dummy values
+- `.env.local` — gitignored, developer-specific overrides (actual API keys, local service URLs)
+- `.env.development` — gitignored, shared dev defaults (can be committed if values are non-sensitive)
+- `.env.production` — injected by CI/CD, never committed
+
+Validate all required variables at startup. An app that silently uses `undefined` for a missing API URL is worse than one that crashes immediately with a clear error:
+
+```typescript
+// lib/env.ts — validate at module load time
+import { z } from "zod";
+
+const envSchema = z.object({
+  VITE_API_URL: z.string().url(),
+  VITE_FEATURE_FLAGS: z.string().default(""),
+});
+
+export const env = envSchema.parse(import.meta.env);
+```
+
+### Docker for Local Services
+
+Run local dependencies (databases, caches, queues, email servers) in Docker to keep developer machines clean and ensure consistency:
+
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: postgres:16-alpine
+    ports: ["5432:5432"]
+    environment:
+      POSTGRES_DB: myapp_dev
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports: ["6379:6379"]
+
+  mailpit:
+    image: axllent/mailpit
+    ports:
+      - "1025:1025"   # SMTP
+      - "8025:8025"   # Web UI
+
+volumes:
+  postgres_data:
+```
+
+Document the setup in the README: `docker compose up -d` starts all services. Never require developers to install PostgreSQL, Redis, or other services directly on their machines.
+
+### Getting to Zero-Friction Setup
+
+Document the new developer setup flow and time it. Target under 10 minutes from fresh checkout to running app. Anything over 15 minutes will be skipped and developers will use workarounds.
+
+Minimum `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:full": "docker compose up -d && vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+Include a `Makefile` or `justfile` for multi-step setup commands that developers run once (`make setup` installs deps, configures git hooks, copies `.env.example`).
+
+### Browser Devtools Configuration
+
+Install and configure browser extensions that accelerate debugging:
+
+- **React Developer Tools**: Component tree inspection, props/state browser, profiler for render performance.
+- **Redux DevTools** (if using Redux): Action/state history, time-travel debugging.
+- **Vite plugin for browser devtools**: Install `vite-plugin-inspect` to visualize the Vite plugin pipeline and module graph.
+
+Configure source maps in development (`devtool: "eval-source-map"` in webpack or `sourcemap: true` in Vite) so stack traces point to TypeScript source, not compiled JavaScript. Without this, debugging is nearly impossible.
+
+### TypeScript Strict Mode
+
+Enable strict mode from day one in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+Disabling strict mode to make TypeScript "less annoying" creates a false sense of safety. The errors strict mode surfaces are real bugs. Fix them instead of disabling the check.
+
+### VS Code Workspace Settings
+
+Commit a `.vscode/settings.json` with recommended settings so all developers use consistent formatting:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "typescript.preferences.importModuleSpecifier": "non-relative"
+}
+```
+
+Commit `.vscode/extensions.json` with recommended extensions. Developers are prompted to install them on workspace open.