@jasonshimmy/vite-plugin-cer-app 0.5.0 → 0.7.0

package/src/__tests__/plugin/virtual/routes.test.ts

@@ -335,6 +335,71 @@ describe('generateRoutesCode — meta.transition', () => {
   })
 })
 
+// ─── meta.render ──────────────────────────────────────────────────────────────
+
+describe('generateRoutesCode — meta.render', () => {
+  beforeEach(() => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(scanDirectory).mockResolvedValue([])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+  })
+
+  it('emits meta.render "server" when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { render: 'server' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('render: "server"')
+  })
+
+  it('emits meta.render "spa" when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/profile.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { render: 'spa' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('render: "spa"')
+  })
+
+  it('emits meta.render "static" when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { render: 'static' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('render: "static"')
+  })
+
+  it('omits render meta when not declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-about', () => html\`<h1>About</h1>\`)` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('render:')
+  })
+
+  it('ignores unknown render values', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { render: 'unknown' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('render:')
+  })
+
+  it('can combine render with layout', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { render: 'server', layout: 'admin' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('render: "server"')
+    expect(code).toContain('layout: "admin"')
+  })
+})
+
 // ─── nested layouts (layoutChain) ────────────────────────────────────────────
 
 describe('generateRoutesCode — layoutChain (nested layouts)', () => {

package/src/__tests__/runtime/isr-handler.test.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { createIsrHandler } from '../../runtime/isr-handler.js'
+
+// ─── Test helpers ─────────────────────────────────────────────────────────────
+
+function mockReq(url = '/page') {
+  return { url, headers: {}, method: 'GET' } as unknown as IncomingMessage
+}
+
+type MockRes = ServerResponse & { header(k: string): string | undefined; body(): string }
+
+function mockRes(): MockRes {
+  const headers: Record<string, string> = {}
+  let body = ''
+  let status = 200
+  return {
+    get statusCode() { return status },
+    set statusCode(v: number) { status = v },
+    setHeader: vi.fn((k: string, v: string) => { headers[k.toLowerCase()] = v }),
+    write: vi.fn(),
+    end: vi.fn((b?: string) => { if (b) body = b }),
+    header: (k: string) => headers[k.toLowerCase()],
+    body: () => body,
+  } as unknown as MockRes
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+// ─── Pass-through for non-ISR routes ─────────────────────────────────────────
+
+describe('createIsrHandler — non-ISR routes', () => {
+  it('calls handler directly when route has no revalidate', async () => {
+    const routes = [{ path: '/about' }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('ok'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/about'), mockRes())
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not set X-Cache header for non-ISR routes', async () => {
+    const routes = [{ path: '/about' }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('ok'))
+    const wrapped = createIsrHandler(routes, handler)
+    const res = mockRes()
+    await wrapped(mockReq('/about'), res)
+    expect(res.header('x-cache')).toBeUndefined()
+  })
+
+  it('passes through when no routes match the URL', async () => {
+    const routes = [{ path: '/contact', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('ok'))
+    const wrapped = createIsrHandler(routes, handler)
+    const res = mockRes()
+    await wrapped(mockReq('/about'), res) // /about has no route
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(res.header('x-cache')).toBeUndefined()
+  })
+})
+
+// ─── Cache miss (first request) ───────────────────────────────────────────────
+
+describe('createIsrHandler — cache miss', () => {
+  it('serves X-Cache: HIT on the first request to an ISR route', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>v1</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    const res = mockRes()
+    await wrapped(mockReq('/page'), res)
+    expect(res.header('x-cache')).toBe('HIT')
+  })
+
+  it('renders via handler on cache miss', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>content</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes())
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('passes the correct URL to the handler during cache rendering', async () => {
+    const routes = [{ path: '/blog/:slug', meta: { ssg: { revalidate: 60 } } }]
+    let capturedUrl = ''
+    const handler = vi.fn((req: IncomingMessage, res: ServerResponse) => {
+      capturedUrl = req.url ?? ''
+      res.end('<html/>')
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/blog/hello'), mockRes())
+    expect(capturedUrl).toBe('/blog/hello')
+  })
+})
+
+// ─── Cache hit (within TTL) ───────────────────────────────────────────────────
+
+describe('createIsrHandler — cache hit', () => {
+  it('serves X-Cache: HIT from cache on second request within TTL', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>v1</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.header('x-cache')).toBe('HIT')
+  })
+
+  it('does not call handler again on cache hit', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>v1</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    await wrapped(mockReq('/page'), mockRes())
+    expect(handler).toHaveBeenCalledTimes(1) // no re-render
+  })
+
+  it('serves the cached HTML body', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>cached body</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.body()).toBe('<html>cached body</html>')
+  })
+
+  it('forwards cached response headers', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8')
+      res.end('<html/>')
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.header('content-type')).toBe('text/html; charset=utf-8')
+  })
+
+  it('forwards cached HTTP status code', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      res.statusCode = 200
+      res.end('<html/>')
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.statusCode).toBe(200)
+  })
+})
+
+// ─── Stale (TTL expired) ──────────────────────────────────────────────────────
+
+describe('createIsrHandler — stale-while-revalidate', () => {
+  it('serves X-Cache: STALE when TTL has expired (revalidate: 0)', async () => {
+    // revalidate: 0 means TTL is always expired after first render
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>v1</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime (HIT)
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.header('x-cache')).toBe('STALE')
+  })
+
+  it('serves stale HTML body immediately while revalidating in background', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => res.end('<html>stale content</html>'))
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/page'), res2)
+    expect(res2.body()).toBe('<html>stale content</html>')
+  })
+
+  it('triggers a background re-render when stale', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    let callCount = 0
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      callCount++
+      res.end(`<html>v${callCount}</html>`)
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime (callCount=1)
+    await wrapped(mockReq('/page'), mockRes()) // stale → triggers background render (callCount=2)
+    await new Promise((r) => setTimeout(r, 0)) // let background render settle
+    expect(callCount).toBe(2)
+  })
+
+  it('does not spawn a second background render while one is in flight', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    let callCount = 0
+    let resolveHung: (() => void) | undefined
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      callCount++
+      if (callCount === 1) {
+        res.end('<html>initial</html>')
+      } else {
+        // Simulate a slow background re-render that never ends in this test
+        new Promise<void>((r) => { resolveHung = r }).then(() => res.end('<html>refreshed</html>'))
+      }
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    await wrapped(mockReq('/page'), mockRes()) // stale → background render in flight
+    // Third request while background render still in flight — should NOT spawn another
+    await wrapped(mockReq('/page'), mockRes())
+    expect(callCount).toBe(2) // still only 2 renders
+    resolveHung?.() // clean up
+  })
+
+  it('resets revalidating flag when background render fails', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    let callCount = 0
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      callCount++
+      if (callCount === 1) {
+        res.end('<html>initial</html>')
+      } else {
+        throw new Error('render failed')
+      }
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page'), mockRes()) // prime
+    await wrapped(mockReq('/page'), mockRes()) // stale → background render throws
+    await new Promise((r) => setTimeout(r, 0)) // let background render settle
+
+    // After failed background render, revalidating flag should be reset.
+    // The third request should trigger a new background render (callCount=3).
+    const res3 = mockRes()
+    await wrapped(mockReq('/page'), res3)
+    expect(res3.header('x-cache')).toBe('STALE')
+    expect(callCount).toBe(3) // a new render was triggered
+  })
+
+  it('resets revalidating flag after 30s timeout (hung render)', async () => {
+    vi.useFakeTimers()
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 0 } } }]
+    let callCount = 0
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => {
+      callCount++
+      if (callCount === 1) res.end('<html>initial</html>')
+      // callCount >= 2: hung — never calls res.end()
+    })
+    const wrapped = createIsrHandler(routes, handler)
+
+    // Prime the cache (synchronous handler, resolves immediately)
+    await wrapped(mockReq('/page'), mockRes())
+    // Trigger stale + hung background render
+    await wrapped(mockReq('/page'), mockRes())
+
+    // Advance clock past 30s — revalidating flag should be reset by timeout
+    vi.advanceTimersByTime(31_000)
+
+    // After timeout reset, a new request should be able to start a fresh revalidation
+    const res3 = mockRes()
+    await wrapped(mockReq('/page'), res3)
+    expect(callCount).toBeGreaterThan(2) // a new render attempt was made
+    expect(res3.header('x-cache')).toBe('STALE')
+  })
+})
+
+// ─── Query string handling ─────────────────────────────────────────────────────
+
+describe('createIsrHandler — query string handling', () => {
+  it('strips query string when looking up the cache key', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => { res.end('<html>content</html>') })
+    const wrapped = createIsrHandler(routes, handler)
+    // Prime with a query-string URL
+    await wrapped(mockReq('/page?foo=bar'), mockRes())
+    // Second request with a different query string — should still be a cache HIT
+    const res2 = mockRes()
+    await wrapped(mockReq('/page?baz=qux'), res2)
+    expect(res2.header('x-cache')).toBe('HIT')
+    expect(handler).toHaveBeenCalledTimes(1) // only one render; second served from cache
+  })
+
+  it('serves the cached HTML regardless of query string variation', async () => {
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => { res.end('<html>cached</html>') })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page?v=1'), mockRes())
+    const res2 = mockRes()
+    await wrapped(mockReq('/page?v=2'), res2)
+    expect(res2.body()).toBe('<html>cached</html>')
+  })
+
+  it('passes the stripped URL (no query string) to the handler during cache render', async () => {
+    // _renderForCache always uses the path-only URL for the fake request so the
+    // handler renders the canonical path, not a query-string-specific variant.
+    const routes = [{ path: '/page', meta: { ssg: { revalidate: 60 } } }]
+    let capturedUrl = ''
+    const handler = vi.fn((req: IncomingMessage, res: ServerResponse) => {
+      capturedUrl = req.url ?? ''
+      res.end('<html/>')
+    })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/page?source=test'), mockRes())
+    expect(capturedUrl).toBe('/page')
+  })
+})
+
+// ─── render mode compatibility ────────────────────────────────────────────────
+
+describe('createIsrHandler — render mode compatibility', () => {
+  it('caches a route with meta.render: server when revalidate is set', async () => {
+    // ISR applies to any route with meta.ssg.revalidate regardless of meta.render.
+    // render: 'server' controls SSG build-time behavior; ISR is a runtime cache layer.
+    const routes = [{ path: '/dashboard', meta: { render: 'server', ssg: { revalidate: 60 } } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => { res.end('<html>dash</html>') })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/dashboard'), mockRes()) // prime
+    const res2 = mockRes()
+    await wrapped(mockReq('/dashboard'), res2)
+    expect(res2.header('x-cache')).toBe('HIT')
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not cache a route with meta.render: server when revalidate is absent', async () => {
+    const routes = [{ path: '/dashboard', meta: { render: 'server' } }]
+    const handler = vi.fn((_: IncomingMessage, res: ServerResponse) => { res.end('<html>dash</html>') })
+    const wrapped = createIsrHandler(routes, handler)
+    await wrapped(mockReq('/dashboard'), mockRes())
+    const res2 = mockRes()
+    await wrapped(mockReq('/dashboard'), res2)
+    expect(res2.header('x-cache')).toBeUndefined()
+    expect(handler).toHaveBeenCalledTimes(2) // no cache — handler called each time
+  })
+})

package/src/cli/commands/preview-isr.ts

@@ -49,6 +49,25 @@ export function matchRoutePattern(pattern: string, urlPath: string): boolean {
   return new RegExp(regexStr).test(norm(urlPath))
 }
 
+/**
+ * Returns the per-route `render` strategy ('static' | 'server' | 'spa') for
+ * the route that best matches `urlPath`, or `null` when no route matches or
+ * none declares a render mode.
+ */
+export function findRenderMode(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  urlPath: string,
+): 'static' | 'server' | 'spa' | null {
+  for (const route of routes) {
+    if (matchRoutePattern(route.path, urlPath)) {
+      const render = route.meta?.render
+      if (render === 'static' || render === 'server' || render === 'spa') return render
+      return null
+    }
+  }
+  return null
+}
+
 /**
  * Looks up the `meta.ssg.revalidate` TTL (in seconds) for the route that best
  * matches `urlPath`. Returns `null` when no route matches or none defines

package/src/cli/commands/preview.ts

@@ -7,6 +7,7 @@ import {
   type IsrCacheEntry,
   type SsrHandlerFn,
   findRevalidate,
+  findRenderMode,
   renderForIsr,
   serveFromIsrCache,
 } from './preview-isr.js'
@@ -200,6 +201,51 @@ export function previewCommand(): Command {
             if (served) return
           }
 
+          // Per-route render strategy — checked before ISR.
+          const renderMode = findRenderMode(pageRoutes, urlPath)
+
+          // render: 'spa' — skip SSR, serve the client index.html shell.
+          if (renderMode === 'spa') {
+            const spaIndex = join(distDir, 'client/index.html')
+            if (existsSync(spaIndex)) {
+              res.setHeader('Content-Type', 'text/html; charset=utf-8')
+              res.setHeader('Cache-Control', 'no-cache')
+              createReadStream(spaIndex).pipe(res)
+            } else {
+              res.statusCode = 404
+              res.setHeader('Content-Type', 'text/plain')
+              res.end('Not Found')
+            }
+            return
+          }
+
+          // render: 'static' — try pre-rendered HTML from dist/, fall through to SSR.
+          if (renderMode === 'static') {
+            const staticFile = urlPath === '/'
+              ? join(distDir, 'index.html')
+              : join(distDir, urlPath.replace(/^\//, ''), 'index.html')
+            if (existsSync(staticFile)) {
+              res.setHeader('Content-Type', 'text/html; charset=utf-8')
+              res.setHeader('Cache-Control', 'no-cache')
+              createReadStream(staticFile).pipe(res)
+              return
+            }
+            // Fall through to SSR if no pre-rendered file exists.
+          }
+
+          // render: 'server' — always SSR, bypass ISR cache.
+          if (renderMode === 'server') {
+            try {
+              await handler(req, res)
+            } catch (err) {
+              console.error('[cer-app] SSR handler error:', err)
+              res.statusCode = 500
+              res.setHeader('Content-Type', 'text/plain')
+              res.end('Internal Server Error')
+            }
+            return
+          }
+
           // ISR: check whether this route has a revalidate TTL.
           const revalidate = findRevalidate(pageRoutes, urlPath)
           if (revalidate !== null) {

package/src/cli/create/templates/spa/package.json.tpl

@@ -8,11 +8,11 @@
     "preview": "cer-app preview"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/create/templates/ssg/package.json.tpl

@@ -9,11 +9,11 @@
     "preview": "cer-app preview"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/create/templates/ssr/package.json.tpl

@@ -8,11 +8,11 @@
     "preview": "cer-app preview --ssr"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/plugin/build-ssg.ts

@@ -1,4 +1,4 @@
-import { writeFile, mkdir } from 'node:fs/promises'
+import { writeFile, mkdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'pathe'
 import { createServer, type UserConfig } from 'vite'
@@ -45,6 +45,15 @@ async function collectSsgPaths(
   const dynamicFiles: Array<{ file: string; entry: ReturnType<typeof buildRouteEntry> }> = []
 
   for (const file of files) {
+    // Skip routes that declare render: 'server' or render: 'spa' — they are
+    // either always-SSR or client-only and must not be pre-rendered.
+    try {
+      const src = await readFile(file, 'utf-8')
+      const renderMatch = src.match(/render\s*:\s*['"]([^'"]+)['"]/)
+      const renderMode = renderMatch ? renderMatch[1] : null
+      if (renderMode === 'server' || renderMode === 'spa') continue
+    } catch { /* ignore read errors */ }
+
     const entry = buildRouteEntry(file, config.pagesDir)
 
     if (!entry.isDynamic && !entry.isCatchAll) {
@@ -73,6 +82,7 @@ async function collectSsgPaths(
           const pageMod = await viteServer.ssrLoadModule(file)
           const pageMeta = pageMod.meta ?? pageMod.pageMeta
 
+          if (pageMeta?.render === 'server' || pageMeta?.render === 'spa') continue
           if (pageMeta?.ssg?.paths) {
             const pathsResult = await pageMeta.ssg.paths()
             for (const ctx of pathsResult) {
@@ -131,12 +141,14 @@ async function renderPath(
 
   // Mock req/res for the Express-style handler.
   // The handler internally merges with dist/client/index.html, so we just
-  // capture whatever it ends with.
+  // capture whatever it writes/ends with.
   const mockReq = { url: path, headers: {} }
   return new Promise<string>((resolve, reject) => {
+    const chunks: string[] = []
     const mockRes = {
       setHeader: () => {},
-      end: (body: string) => resolve(body),
+      write: (chunk: string) => { chunks.push(chunk) },
+      end: (body?: string) => resolve(chunks.join('') + (body ?? '')),
     }
     ;(handlerFn as (req: unknown, res: unknown) => Promise<void>)(mockReq, mockRes).catch(reject)
   })

package/src/plugin/dev-server.ts

@@ -108,6 +108,24 @@ function parseQuery(url: string): Record<string, string> {
   return result
 }
 
+/**
+ * Tests whether a route path pattern matches a URL path.
+ * Mirrors the logic in preview-isr.ts#matchRoutePattern — kept local to
+ * avoid a plugin→CLI dependency.
+ */
+function _matchDevRoute(pattern: string, urlPath: string): boolean {
+  const norm = (s: string) => s.replace(/\/+$/, '') || '/'
+  if (norm(pattern) === norm(urlPath)) return true
+  const regexStr =
+    '^' +
+    norm(pattern)
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/:[^/]+\*/g, '.*')
+      .replace(/:[^/]+/g, '[^/]+') +
+    '$'
+  return new RegExp(regexStr).test(norm(urlPath))
+}
+
 /**
  * Configures the Vite dev server with:
  * 1. API route handlers from server/api/
@@ -218,6 +236,21 @@ export function configureCerDevServer(
         (!url.includes('.') && !url.startsWith('/api/'))
 
       if (acceptsHtml) {
+        // Check per-route render mode — skip SSR for 'spa' routes.
+        const urlPathOnly = url.split('?')[0]
+        try {
+          const routesMod = await server.ssrLoadModule('virtual:cer-routes')
+          const pageRoutes = Array.isArray(routesMod.default) ? routesMod.default as Array<{ path: string; meta?: Record<string, unknown> }> : []
+          for (const route of pageRoutes) {
+            if (_matchDevRoute(route.path, urlPathOnly)) {
+              if (route.meta?.render === 'spa') {
+                next()
+                return
+              }
+              break
+            }
+          }
+        } catch { /* module not ready — continue to SSR */ }
         try {
           // Load the SSR entry module
           const ssrEntry = await server.ssrLoadModule(