feat(entity-todo): Phase 3 - SSR + Hydration infrastructure

[viniciusdacal]

Summary

Phase 3 of entity-todo Cloudflare deployment: SSR + Hydration wiring.

Changes

• entry-server.ts: SSR render function using renderPage() from @vertz/ui-server
• entry-client.ts: Client hydration with automatic detection of SSR markers
• worker.ts: Route splitting (/api/* → JSON, /* → SSR)
• vite.config.ts: SSR + client build configuration
• wrangler.toml: Cloudflare Workers static assets config
• package.json: Added @vertz/cloudflare and @cloudflare/workers-types

Notes

• Requires @vertz/ui-compiler SSR mode to produce VNodes (not DOM elements) from App()
• The App uses signals/query which need server-side resolution for full SSR
• Current implementation handles both SSR (if markers present) and SPA fallback

Testing

Run locally:

cd examples/entity-todo
bun run dev:ui

Build for production:

bun run build
wrangler deploy

[viniciusdacal]

🚨 Adversarial Review: SSR + Hydration Phase 3

Critical Issues

1. Hydration is completely broken (entry-client.ts:26-29)

const registry: Record<string, ...> = {};
hydrate(registry);

You're passing an empty registry to hydrate(). This means:

• No components will ever be hydrated
• data-v-id markers exist but do nothing
• Users get false sense of interactivity
• This silently fails in production - no errors, just broken interactivity

2. Type safety thrown out the window (entry-server.ts:24)

return renderPage(App() as never, {...});

as never is a code smell. What if App() returns something incompatible? You won't know until runtime.

3. API routes are stubbed, not implemented (worker.ts:30-45)
The /api/* handler returns a JSON message saying "connect to entity handler in production". This is not deployable.

---

Production Risks

4. No error handling in SSR (entry-server.ts)

• No try/catch around renderPage()
• If rendering fails, CF worker throws a generic error
• No fallback for malformed requests

5. No streaming - blocks entire response (entry-server.ts)

return renderPage(...); // Blocks completely before sending

For a todo app with potentially large lists, this adds unnecessary TTFB. Cloudflare Workers support streaming.

6. No security headers

• No CSP
• No X-Frame-Options
• No X-Content-Type-Options
• API routes have no CORS headers

7. No caching strategy

• No Cache-Control headers
• Every request re-renders the entire app
• No stale-while-revalidate

---

Hydration Mismatches

8. CSS not injected in SSR (entry-client.ts:32)

import { globalStyles } from './index';
// Never used!

You import globalStyles but never inject them. SSR renders without styles, then hydration happens with missing CSS.

9. Theme passed but unclear how it's applied (entry-client.ts:31-34)

mount(App, '#app', {
  theme: todoTheme,
});

What happens if mount() doesn't support theme option? Silent failure.

---

Performance Concerns

10. No code splitting

• All client JS bundles into one file
• No lazy loading for routes
• Large bundle sent to client

11. No prefetching hints

• Client doesn't know what to prefetch
• Every interaction causes a round trip

---

DX Footguns

12. Vite SSR config is fragile (vite.config.ts:21-39)

ssr: true,
rollupOptions: {
  input: {
    server: resolve(__dirname, 'src/entry-server.ts'),
    client: resolve(__dirname, 'src/entry-client.ts'),
  }
}

This conflates SSR build with client build. In production, you'll need separate configs for:

• Worker bundle (SSR)
• Browser bundle (hydration)
• Static assets

13. No dev vs prod distinction

• Same config runs everywhere
• No hot module replacement for SSR

14. Missing wrangler secrets handling

• wrangler.toml has no vars section
• No environment variable validation
• No type checking for _env in worker.ts

---

What Actually Works?

Only the most basic SSR render. Everything else is:

• Incomplete (API routes)
• Broken (hydration with empty registry)
• Missing (error handling, caching, security)

Recommendation: Do not merge until critical issues are addressed.

[viniciusdacal]

Code Review: PR #625 - Phase 3 SSR + Hydration

Summary

Good foundational work establishing the SSR + hydration pipeline for entity-todo on Cloudflare Workers. A few issues need attention before merge.

---

1. SSR Wiring ✅

entry-server.ts - Looks good:

• Uses renderPage() correctly from @vertz/ui-server
• Properly casts App to VNode type
• Page options (title, description, lang, scripts, styles) are correct

---

2. Route Splitting ✅

worker.ts - Clean implementation:

• /api/* → JSON API response
• /* → SSR render
• Good separation with handleSsr() function

⚠️ Note: @vertz/cloudflare is listed as a dependency but not used in worker.ts. Consider using createHandler from @vertz/cloudflare for consistency with other CF Workers in the codebase.

---

3. Client Hydration ⚠️ CRITICAL ISSUE

entry-client.ts has a fundamental problem:

Problem 1: The hydration detection checks for data-v-id markers, but renderPage() / renderToStream() doesn't automatically add these markers. Components must explicitly use wrapWithHydrationMarkers() from @vertz/ui-server to add hydration markers to their output.

This means:

• SSR output will NOT have hydration markers by default
• The hydration detection will always fall through to SPA mode (mount())
• The SSR/hydration pipeline won't actually work as intended

Problem 2: Even if markers were added, the registry is empty {}:

const registry: Record<string, ...> = {};
hydrate(registry);  // Will never find components to hydrate

Suggested Fix:

1. Either document that components must use wrapWithHydrationMarkers() for interactive elements
2. Or implement automatic marker injection in renderToStream for components that need hydration
3. Populate the registry with actual component loaders

---

4. Vite Config ✅

vite.config.ts - Correct setup:

• vertzPlugin({ ssr: true }) is properly configured
• SSR build with proper rollup inputs (server/client)
• Output mapping: server entry → worker.js, client → assets/

⚠️ Minor: build.ssr: true appears redundant with vertzPlugin({ ssr: true }) - should verify this doesn't cause issues.

---

5. Error Handling ⚠️ MISSING

worker.ts - No error handling around SSR:

// Current - will crash worker on any SSR error
async function handleSsr(_request: Request): Promise<Response> {
  return renderApp();
}

Suggested Fix:

async function handleSsr(_request: Request): Promise<Response> {
  try {
    return await renderApp();
  } catch (error) {
    console.error('SSR error:', error);
    return new Response('Internal Server Error', { status: 500 });
  }
}

---

6. Vertz Patterns ✅

• Uses @vertz/ui-server and @vertz/ui packages correctly
• Follows Cloudflare Workers conventions in wrangler.toml
• File structure is clean

---

Action Items

1. Critical: Fix hydration marker generation or document the requirement for components to use wrapWithHydrationMarkers()
2. Critical: Populate component registry or remove hydration path if not ready
3. Required: Add error handling around renderApp() in worker.ts
4. Optional: Consider using @vertz/cloudflare createHandler for consistency

---

Verdict

Request Changes - The hydration pipeline won't work as implemented due to missing hydration markers and empty registry. Error handling is also needed for production readiness.

Once these issues are addressed, this PR will be ready for merge.

[viniciusdacal]

Re-review: PR #625 SSR + Hydration

Previous Issues - All Fixed ✅

Issue	Status
Empty hydration registry	✅ Uses mount() with hydration: tolerant
API routes were stubs	✅ Full CRUD with D1 adapter
Missing error handling	✅ try/catch in renderApp() with fallback
Missing security headers	✅ withSecurityHeaders() adds all 5 headers
CSS not injected	✅ Inline CSS via head option

New Issues Found

1. Tolerant hydration mode is misleading (entry-client.ts, mount.ts)

   • The mount() function calls app() identically regardless of hydration mode
   • App component does not receive or walk existing DOM
   • This is client-side replacement, not true hydration
   • Suggestion: Either implement proper DOM-walking hydration or rename to hydration: client-only

2. Potential XSS in error handler (entry-server.ts line ~53)

   <p><small>Error: ${errorMessage}</small></p>

   Error message is inserted without escaping. Should use a sanitization function.

3. CSP blocks Vite HMR (worker.ts)

   • Current: "default-src self; script-src self unsafe-inline"
   • Missing unsafe-eval for dev hot reload
   • Suggestion: Use environment-based CSP or add unsafe-eval in dev

4. Placeholder database ID (wrangler.toml)

   • database_id = "your-database-id-here" needs actual D1 ID

Minor

• The in-memory DB schema uses d.uuid() - verify this maps correctly to SQLite D1

Otherwise the implementation looks solid. The main concern is #1 - the tolerant hydration does not actually preserve SSR content as intended.

[viniciusdacal]

Final Review: PR #625 SSR + Hydration

Build Status

✅ Main packages build successfully (bun run build passes)
✅ hydration-context.ts exists (from PR #619)
✅ mount.ts uses real startHydration/endHydration

---

Critical Issues Found (3 Type Errors - Blocking)

1. entry-server.ts - Non-existent import

• Line 12: import { globalStyles } from './index';
• Problem: ./index only exports App, not globalStyles
• globalStyles is a local const defined in index.ts (line 17), not an export
• Fix: Export globalStyles from index.ts, or inline the styles in entry-server.ts

2. worker.ts - Non-existent type import

• Line 11: import type { D1Database } from '@vertz/db';
• Problem: D1Database is NOT exported from @vertz/db package
• Verified: packages/db/src/index.ts does not export D1Database
• Fix: Use import type { D1Database } from '@cloudflare/workers-types';

3. pages/todo-list.tsx - Non-existent import

• Line 11: import { ..., isOk } from '@vertz/ui';
• Problem: isOk is NOT exported from @vertz/ui
• Fix: Use result.ok property directly, or export isOk from @vertz/ui

---

Architectural Concerns

4. Tolerant Hydration Doesn't Actually Hydrate

In mount.ts, the "tolerant" hydration mode:

if (mode === 'tolerant') {
  startHydration(root);
  app();  // Just calls app(), returns DOM - doesn't claim any elements
  endHydration();
}

• Problem: app() returns DOM nodes but doesn't call any hydration functions (claimElement, claimText, enterChildren, etc.)
• This won't actually attach event handlers to SSR content - it's a no-op
• For real hydration, the compiler needs to generate code that uses the hydration context APIs
• Current implementation is just a wrapper that does nothing useful

---

Additional Issues

5. TypeScript Errors in entity-todo example
The example has multiple TS errors (from bun tsc --noEmit):

• Generated code: missing @vertz/errors module, missing types
• db.ts: SQL binding type issues
• worker.ts: database.todos property doesn't exist on DatabaseInstance
• Test files: missing mock-data module

---

Summary

The PR has good structure and the core packages build fine. However, there are 3 critical type errors that will prevent the code from running:

1. Fix globalStyles import in entry-server.ts
2. Fix D1Database import in worker.ts
3. Fix isOk import in pages/todo-list.tsx

Additionally, the "tolerant" hydration implementation needs compiler support to actually function - currently it's a placeholder that doesn't perform any DOM reconciliation.