feat(entity-todo): Phase 4 - Local dev experience with Vite HMR

[viniciusdacal]

Summary

Phase 4: Local dev experience for entity-todo example.

Changes

1. New dev-server.ts - Unified dev server that brings together:

   • Vite HMR for UI hot-reload
   • @vertz/server for API routes
   • SPA mode for client-side rendering
   • SQLite for local persistence (not D1)

2. Updated package.json scripts:

   • : starts the unified dev server
   • : builds the production bundle
   • : runs wrangler deploy

3. Fixes:

   • index.ts: Only mount in browser (not SSR)
   • entry-server.ts: Don't import client-side code

Usage

entity-todo-example@ dev /Users/viniciusdacal/openclaw-workspace/vertz/examples/entity-todo
bun run src/dev-server.ts

📦 SQLite database initialized at: /Users/viniciusdacal/openclaw-workspace/vertz/examples/entity-todo/data/todos.db

🚀 Starting Vertz Dev Server...

✅ Vite dev server initialized

╔═══════════════════════════════════════════════════════════╗
║ ║
║ 🏗️ Vertz Dev Server ║
║ ║
║ Local: http://localhost:3000 ║
║ API: http://localhost:3000/api ║
║ ║
║ Stack: ║
║ • Vite HMR (UI hot-reload) ✅ ║
║ • @vertz/server (API routes) ✅ ║
║ • SPA mode (client-side rendering) ║
║ • SQLite (local persistence) ✅ ║
║ ║
║ Notes: ║
║ • API routes served locally with SQLite ║
║ • UI uses Vite HMR for hot-reload ║
║ • For SSR, run: pnpm build && pnpm preview ║
║ ║
║ Available endpoints: ║
║ • GET /api/todos List all todos ║
║ • GET /api/todos/:id Get a todo ║
║ • POST /api/todos Create a todo ║
║ • PATCH /api/todos/:id Update a todo ║
║ • DELETE /api/todos/:id Delete a todo ║
║ ║
╚═══════════════════════════════════════════════════════════╝

👋 Shutting down...

The dev server provides:

• API routes at with SQLite persistence
• Client-side rendering with Vite HMR
• Data persists in

For true SSR, run:

Acceptance Criteria

• pnpm dev starts everything with one command
• UI changes hot-reload without page refresh
• Entity changes trigger server restart (manual)
• Data persists in local SQLite between restarts

Closes #616

[viniciusdacal]

Code Review: PR #629 - Phase 4: Local Dev Experience

Role: Primary Review (Frontend & API Surface Engineer)

Summary

This PR implements the local development experience for entity-todo. Overall the implementation is solid.

1. Dev Server ✅

• Uses bun run src/dev-server.ts correctly (Bun is the team runtime)
• Unified server combines Vite + API routes + SPA + SQLite
• Port correctly defaults to 3000 from env

2. Vite HMR Integration ✅

• Properly configured with middlewareMode and appType custom
• HMR clientPort set correctly
• Last commit (d764c8e) correctly removed /api proxy to prevent infinite loop with dev-server middleware

3. SQLite Persistence ✅

• Uses bun:sqlite (correct per team conventions)
• Full DbDriver interface implementation
• Creates data/ directory if missing
• Migration support with proper table creation
• SQL injection protection: Whitelist approach in list() method for WHERE columns

4. Error Handling ✅

• db.ts: Try/catch with user-friendly messages
• entry-server.ts: SSR wrapped in try/catch, returns SPA fallback on error
• worker.ts: D1 binding validation + try/catch in all handlers + security headers
• dev-server.ts: Top-level try/catch returns 500

5. Minor Notes

• The vite.config.ts comment about proxy removal is a bit abrupt but harmless
• Good separation between dev (SQLite) and prod (D1) persistence

Verdict

Approved. Clean implementation that meets all acceptance criteria.

[viniciusdacal]

Adversarial Review: Local Dev Experience

Found several issues that could cause problems for developers:

Critical Issues

1. Package Manager Confusion (DX Footgun)

   • package.json uses bun run for dev script (correct for team)
   • But docs/comments reference pnpm dev, pnpm build && pnpm preview
   • Developers will be confused about which package manager to use

2. Hardcoded localhost in Request conversion

   • toWebRequest() hardcodes http://localhost:PORT
   • Breaks in containerized dev environments or reverse proxies

3. PR Has Merge Conflicts

   • This PR is marked as CONFLICTING
   • Cannot be merged until resolved

Medium Issues

4. No CORS Headers

   • API at /api/* has zero CORS configuration
   • Developers calling API from separate frontend origins will fail

5. Database Not Closed on Shutdown

   • SQLite driver close() is never called in graceful shutdown
   • Can leave WAL files in inconsistent state

6. Console.log in Production Code

   • console.log(Entity Todo app mounted) in index.ts runs in all environments
   • Should be wrapped in import.meta.DEV

7. No Request Body Validation

   • POST/PATCH handlers dont validate Content-Type
   • Accepts any body without checking its valid JSON

Minor Issues

8. No Rate Limiting

   • SQLite dev server has no rate limiting

9. No Input Length Limits

   • No max length on title field

Summary

The core functionality works, but the DX has several footguns. Package manager mismatch and missing CORS are most impactful.