npm - @jasonshimmy/vite-plugin-cer-app - Versions diffs - 0.6.0 → 0.7.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/CHANGELOG.md +4 -0
package/IMPLEMENTATION_PLAN.md +2 -2
package/commits.txt +1 -1
package/dist/cli/commands/preview-isr.d.ts +9 -0
package/dist/cli/commands/preview-isr.d.ts.map +1 -1
package/dist/cli/commands/preview-isr.js +16 -0
package/dist/cli/commands/preview-isr.js.map +1 -1
package/dist/cli/commands/preview.d.ts.map +1 -1
package/dist/cli/commands/preview.js +44 -1
package/dist/cli/commands/preview.js.map +1 -1
package/dist/plugin/build-ssg.d.ts.map +1 -1
package/dist/plugin/build-ssg.js +13 -1
package/dist/plugin/build-ssg.js.map +1 -1
package/dist/plugin/dev-server.d.ts.map +1 -1
package/dist/plugin/dev-server.js +33 -0
package/dist/plugin/dev-server.js.map +1 -1
package/dist/plugin/virtual/routes.d.ts.map +1 -1
package/dist/plugin/virtual/routes.js +24 -2
package/dist/plugin/virtual/routes.js.map +1 -1
package/dist/runtime/entry-server-template.d.ts +1 -1
package/dist/runtime/entry-server-template.d.ts.map +1 -1
package/dist/runtime/entry-server-template.js +21 -4
package/dist/runtime/entry-server-template.js.map +1 -1
package/dist/runtime/isr-handler.d.ts +40 -0
package/dist/runtime/isr-handler.d.ts.map +1 -0
package/dist/runtime/isr-handler.js +152 -0
package/dist/runtime/isr-handler.js.map +1 -0
package/dist/types/page.d.ts +14 -0
package/dist/types/page.d.ts.map +1 -1
package/docs/data-loading.md +69 -2
package/docs/rendering-modes.md +63 -2
package/docs/routing.md +33 -0
package/e2e/cypress/e2e/error-boundary.cy.ts +43 -0
package/e2e/cypress/e2e/isr-nested-runtime.cy.ts +6 -4
package/e2e/cypress/e2e/per-route-render.cy.ts +70 -0
package/e2e/kitchen-sink/app/error.ts +7 -2
package/e2e/kitchen-sink/app/pages/loader-error-test.ts +13 -0
package/e2e/kitchen-sink/app/pages/render-server-test.ts +12 -0
package/e2e/kitchen-sink/app/pages/render-spa-test.ts +12 -0
package/package.json +5 -1
package/src/__tests__/cli/preview-isr.test.ts +44 -0
package/src/__tests__/plugin/build-ssg.test.ts +126 -1
package/src/__tests__/plugin/dev-server.test.ts +91 -0
package/src/__tests__/plugin/entry-server-template.test.ts +53 -0
package/src/__tests__/plugin/virtual/routes.test.ts +65 -0
package/src/__tests__/runtime/isr-handler.test.ts +331 -0
package/src/cli/commands/preview-isr.ts +19 -0
package/src/cli/commands/preview.ts +46 -0
package/src/plugin/build-ssg.ts +11 -1
package/src/plugin/dev-server.ts +33 -0
package/src/plugin/virtual/routes.ts +24 -2
package/src/runtime/entry-server-template.ts +21 -4
package/src/runtime/isr-handler.ts +183 -0
package/src/types/page.ts +14 -0

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/plugin/build-ssg.ts CHANGED Viewed

@@ -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) {

package/src/plugin/dev-server.ts CHANGED Viewed

@@ -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(

package/src/plugin/virtual/routes.ts CHANGED Viewed

@@ -64,6 +64,23 @@ function extractTransition(source: string): string | boolean | null {
   return null
 }
+/**
+ * Extracts the per-route `render` strategy from a page file's source.
+ * Returns 'static', 'server', 'spa', or null if absent.
+ *
+ * Matches patterns like:
+ *   render: 'server'
+ *   render: 'spa'
+ *   render: 'static'
+ */
+function extractRender(source: string): 'static' | 'server' | 'spa' | null {
+  const match = source.match(/render\s*:\s*['"]([^'"]+)['"]/)
+  if (!match) return null
+  const val = match[1]
+  if (val === 'static' || val === 'server' || val === 'spa') return val
+  return null
+}
 /**
  * Resolves the layout chain for a page by walking its ancestor directories
  * inside pagesDir looking for `_layout.ts` files. Each `_layout.ts` must
@@ -162,6 +179,7 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
     layoutChain: string[] | null
     revalidate: number | null
     transition: string | boolean | null
+    render: 'static' | 'server' | 'spa' | null
   }> = await Promise.all(
     sorted.map(async (entry) => {
       try {
@@ -174,9 +192,10 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
           layoutChain,
           revalidate: extractRevalidate(src),
           transition: extractTransition(src),
+          render: extractRender(src),
         }
       } catch {
-        return { middleware: [], layout: null, layoutChain: null, revalidate: null, transition: null }
+        return { middleware: [], layout: null, layoutChain: null, revalidate: null, transition: null, render: null }
       }
     }),
   )
@@ -185,7 +204,7 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
   // Build routes array with lazy load() functions for code splitting.
   const routeItems = sorted.map((entry, i) => {
-    const { middleware: mw, layout, layoutChain, revalidate, transition } = metaPerEntry[i]
+    const { middleware: mw, layout, layoutChain, revalidate, transition, render } = metaPerEntry[i]
     const filePath = JSON.stringify(entry.filePath)
     const tagName = JSON.stringify(entry.tagName)
     const routePath = JSON.stringify(entry.routePath)
@@ -209,6 +228,9 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
     if (transition !== null) {
       metaFields.push(`transition: ${JSON.stringify(transition)}`)
     }
+    if (render !== null) {
+      metaFields.push(`render: ${JSON.stringify(render)}`)
+    }
     const metaStr = metaFields.length > 0 ? `    meta: { ${metaFields.join(', ')} },\n` : ''
     if (mw.length === 0) {

package/src/runtime/entry-server-template.ts CHANGED Viewed

@@ -27,6 +27,8 @@ import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } f
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
 import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { errorTag } from 'virtual:cer-error'
+import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
 registerBuiltinComponents()
 initRuntimeConfig(runtimeConfig)
@@ -155,8 +157,18 @@ const _prepareRequest = async (req) => {
           head = \`<script>window.__CER_DATA__ = \${JSON.stringify(data)}</script>\`
         }
       }
-    } catch {
-      // Non-fatal: loader errors fall back to an empty page; client will refetch.
+    } catch (err) {
+      // Loader threw — render the error page server-side if app/error.ts exists.
+      const status = (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number')
+        ? err.status : 500
+      const message = (err instanceof Error) ? err.message : String(err)
+      if (!errorTag) {
+        console.error('[cer-app] Loader error (no app/error.ts defined):', err)
+      }
+      const errVnode = errorTag
+        ? { tag: errorTag, props: { attrs: { error: message, status: String(status) } }, children: [] }
+        : { tag: 'div', props: {}, children: [] }
+      return { vnode: errVnode, router, head: undefined, status }
     }
   }
@@ -172,12 +184,13 @@ const _prepareRequest = async (req) => {
     if (tag) vnode = { tag, props: {}, children: [vnode] }
   }
-  return { vnode, router, head }
+  return { vnode, router, head, status: null }
 }
 export const handler = async (req, res) => {
   await _cerDataStore.run(null, async () => {
-    const { vnode, router, head } = await _prepareRequest(req)
+    const { vnode, router, head, status } = await _prepareRequest(req)
+    if (status != null) res.statusCode = status
     // Begin collecting useHead() calls made during the synchronous render pass.
     // IMPORTANT: the stream's start() function runs synchronously on construction,
@@ -236,6 +249,10 @@ export const handler = async (req, res) => {
   })
 }
+// ISR-wrapped handler for production integrations (Express, Hono, Fastify).
+// Routes with meta.ssg.revalidate are served stale-while-revalidate.
+export const isrHandler = createIsrHandler(routes, handler)
 export { apiRoutes, plugins, layouts, routes }
 export default handler
 `