@jasonshimmy/vite-plugin-cer-app 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [v0.12.0] - 2026-03-22
+
+- feat: implement ISR support with isrHandler for SSR fallback in Cloudflare, Netlify, and Vercel adapters (ddcc4d4)
+
 ## [v0.11.0] - 2026-03-22
 
 - feat: add Cloudflare Pages adapter for SSR and SSG support (2734c26)

package/IMPLEMENTATION_PLAN.md

@@ -287,6 +287,10 @@ Requires a `revalidate` option per route (via `meta.ssg.revalidate: 60`).
 
 **Files:**
 - `src/cli/commands/preview.ts` — ISR cache layer
+- `src/runtime/isr-handler.ts` — `createIsrHandler` factory (shared by all platforms)
+- `src/cli/adapters/vercel.ts` — uses `isrHandler` for SSR fallback
+- `src/cli/adapters/netlify.ts` — uses `isrHandler` for SSR fallback
+- `src/cli/adapters/cloudflare.ts` — uses `isrHandler` for SSR fallback
 - `src/plugin/virtual/routes.ts` — include `meta.ssg.revalidate` in route
 - `src/types/page.ts` — add `revalidate` to `PageSsgConfig`
 

package/commits.txt

@@ -1 +1 @@
-- feat: add Cloudflare Pages adapter for SSR and SSG support (2734c26)
+- feat: implement ISR support with isrHandler for SSR fallback in Cloudflare, Netlify, and Vercel adapters (ddcc4d4)

package/dist/cli/adapters/cloudflare.js

@@ -51,7 +51,7 @@ import { Readable } from 'node:stream'
 // Must be set before the dynamic import below resolves.
 globalThis.__CER_CLIENT_TEMPLATE__ = \`${escaped}\`
 
-const { handler, apiRoutes, runServerMiddleware, runWithRequestContext } = await import('./server/server.js')
+const { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } = await import('./server/server.js')
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -172,8 +172,8 @@ async function handleRequest(webReq) {
     return new Response('Not Found', { status: 404 })
   }
 
-  // All other requests: SSR.
-  handler(nodeReq, res).catch(() => {
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  isrHandler(nodeReq, res).catch(() => {
     if (!res.writableEnded) {
       res.statusCode = 500
       res.end('Internal Server Error')

package/dist/cli/adapters/netlify.js

@@ -38,7 +38,7 @@ import { existsSync, mkdirSync, writeFileSync, copyFileSync, cpSync, readdirSync
 const NETLIFY_SSR_BRIDGE = `\
 // Auto-generated by @jasonshimmy/vite-plugin-cer-app — do not edit.
 import { Readable } from 'node:stream'
-import { handler, apiRoutes, runServerMiddleware, runWithRequestContext } from '../../dist/server/server.js'
+import { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } from '../../dist/server/server.js'
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -161,8 +161,8 @@ export default async (webReq) => {
     return new Response('Not Found', { status: 404 })
   }
 
-  // All other requests: SSR.
-  handler(nodeReq, res).catch(() => {
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  isrHandler(nodeReq, res).catch(() => {
     if (!res.writableEnded) {
       res.statusCode = 500
       res.end('Internal Server Error')

package/dist/cli/adapters/vercel.js

@@ -30,7 +30,7 @@ import { existsSync, mkdirSync, writeFileSync, copyFileSync, cpSync, readdirSync
  */
 const VERCEL_LAUNCHER = `\
 // Auto-generated by @jasonshimmy/vite-plugin-cer-app — do not edit.
-import { handler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'
+import { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -120,8 +120,8 @@ export default async function cerAppHandler(req, res) {
     return
   }
 
-  // All other requests: SSR.
-  await handler(req, res)
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  await isrHandler(req, res)
 }
 `;
 // ─── Public API ───────────────────────────────────────────────────────────────

package/docs/rendering-modes.md

@@ -227,7 +227,7 @@ Any CDN or static host. Upload the entire `dist/` directory (excluding `dist/ser
 
 ## ISR — Incremental Static Regeneration
 
-ISR is a per-route cache layer in the SSR preview server. Pages with `meta.ssg.revalidate` set are rendered once, cached, and re-rendered in the background when the TTL expires (stale-while-revalidate).
+ISR is a per-route cache layer built into the SSR server bundle. Pages with `meta.ssg.revalidate` set are rendered once, cached in memory, and re-rendered in the background when the TTL expires (stale-while-revalidate). It works identically in the preview server, on Vercel, on Netlify, and on Cloudflare Pages — no extra configuration required.
 
 ### How it works
 
@@ -266,9 +266,9 @@ export const meta = {
 
 ISR caches by **path only** — query strings are stripped from the cache key. Requests to `/blog/post?preview=true` and `/blog/post` share the same cache entry. Use `render: 'server'` (no `revalidate`) for routes where query parameters affect the rendered output.
 
-### Decision order in the preview server
+### Decision order (preview server and hosting adapters)
 
-The built-in preview server resolves each request using this precedence:
+The built-in preview server — and the generated entry points for Vercel, Netlify, and Cloudflare — resolve each request using this precedence:
 
 1. Static asset (`dist/client/**.*`) — served directly
 2. `render: 'spa'` — returns `dist/client/index.html` (SPA shell)
@@ -293,9 +293,19 @@ ISR is controlled solely by `meta.ssg.revalidate`. The `meta.render` override is
 
 ### Availability
 
-ISR is active in the built-in **preview server** (`cer-app preview`) and in production via the `isrHandler` export from the server bundle.
+ISR is active everywhere the `isrHandler` from the server bundle is used:
 
-**Production (Express):**
+| Environment | ISR supported |
+|---|---|
+| `cer-app preview` (built-in preview server) | ✅ |
+| Vercel (via `cer-app adapt vercel`) | ✅ |
+| Netlify (via `cer-app adapt netlify`) | ✅ |
+| Cloudflare Pages (via `cer-app adapt cloudflare`) | ✅ |
+| Custom Express / Node.js server | ✅ (use `isrHandler` directly) |
+
+The in-memory ISR cache is per-process. On platforms that spin up multiple instances (Vercel, Netlify), each instance maintains its own cache — this is consistent with how Next.js and other frameworks handle ISR at the edge.
+
+**Custom Node.js server (Express):**
 ```ts
 import express from 'express'
 import sirv from 'sirv'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [

package/src/__tests__/cli/adapters/cloudflare.test.ts

@@ -76,6 +76,13 @@ describe('runCloudflareAdapter — SSR mode', () => {
     expect(worker).toContain('Readable')
   })
 
+  it('worker imports isrHandler and uses it for SSR fallback (enables ISR stale-while-revalidate)', async () => {
+    await runCloudflareAdapter(root)
+    const worker = readText(root, 'dist/_worker.js')
+    expect(worker).toContain('isrHandler')
+    expect(worker).toContain('isrHandler(nodeReq, res)')
+  })
+
   it('worker handles /api/* routing via matchApiPattern', async () => {
     await runCloudflareAdapter(root)
     const worker = readText(root, 'dist/_worker.js')

package/src/__tests__/cli/adapters/netlify.test.ts

@@ -51,6 +51,13 @@ describe('runNetlifyAdapter — SSR mode', () => {
     expect(bridge).toContain("from '../../dist/server/server.js'")
   })
 
+  it('bridge imports isrHandler and uses it for SSR fallback (enables ISR stale-while-revalidate)', async () => {
+    await runNetlifyAdapter(root)
+    const bridge = readText(root, 'netlify/functions/ssr.mjs')
+    expect(bridge).toContain('isrHandler')
+    expect(bridge).toContain('isrHandler(nodeReq, res)')
+  })
+
   it('bridge exports a default async function', async () => {
     await runNetlifyAdapter(root)
     const bridge = readText(root, 'netlify/functions/ssr.mjs')

package/src/__tests__/cli/adapters/vercel.test.ts

@@ -96,10 +96,17 @@ describe('runVercelAdapter — SSR mode', () => {
     await runVercelAdapter(root)
     expect(existsSync(join(root, '.vercel/output/functions/index.func/index.js'))).toBe(true)
     const launcher = readText(root, '.vercel/output/functions/index.func/index.js')
-    expect(launcher).toContain("import { handler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'")
+    expect(launcher).toContain("import { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'")
     expect(launcher).toContain('export default async function cerAppHandler')
   })
 
+  it('launcher uses isrHandler for SSR fallback (enables ISR stale-while-revalidate)', async () => {
+    await runVercelAdapter(root)
+    const launcher = readText(root, '.vercel/output/functions/index.func/index.js')
+    expect(launcher).toContain('isrHandler')
+    expect(launcher).toContain('await isrHandler(req, res)')
+  })
+
   it('launcher routes /api/* requests to apiRoutes', async () => {
     await runVercelAdapter(root)
     const launcher = readText(root, '.vercel/output/functions/index.func/index.js')

package/src/cli/adapters/cloudflare.ts

@@ -64,7 +64,7 @@ import { Readable } from 'node:stream'
 // Must be set before the dynamic import below resolves.
 globalThis.__CER_CLIENT_TEMPLATE__ = \`${escaped}\`
 
-const { handler, apiRoutes, runServerMiddleware, runWithRequestContext } = await import('./server/server.js')
+const { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } = await import('./server/server.js')
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -185,8 +185,8 @@ async function handleRequest(webReq) {
     return new Response('Not Found', { status: 404 })
   }
 
-  // All other requests: SSR.
-  handler(nodeReq, res).catch(() => {
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  isrHandler(nodeReq, res).catch(() => {
     if (!res.writableEnded) {
       res.statusCode = 500
       res.end('Internal Server Error')

package/src/cli/adapters/netlify.ts

@@ -50,7 +50,7 @@ import {
 const NETLIFY_SSR_BRIDGE = `\
 // Auto-generated by @jasonshimmy/vite-plugin-cer-app — do not edit.
 import { Readable } from 'node:stream'
-import { handler, apiRoutes, runServerMiddleware, runWithRequestContext } from '../../dist/server/server.js'
+import { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } from '../../dist/server/server.js'
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -173,8 +173,8 @@ export default async (webReq) => {
     return new Response('Not Found', { status: 404 })
   }
 
-  // All other requests: SSR.
-  handler(nodeReq, res).catch(() => {
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  isrHandler(nodeReq, res).catch(() => {
     if (!res.writableEnded) {
       res.statusCode = 500
       res.end('Internal Server Error')

package/src/cli/adapters/vercel.ts

@@ -42,7 +42,7 @@ import {
  */
 const VERCEL_LAUNCHER = `\
 // Auto-generated by @jasonshimmy/vite-plugin-cer-app — do not edit.
-import { handler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'
+import { handler, isrHandler, apiRoutes, runServerMiddleware, runWithRequestContext } from './server/server.js'
 
 function matchApiPattern(pattern, urlPath) {
   const pp = pattern.split('/')
@@ -132,8 +132,8 @@ export default async function cerAppHandler(req, res) {
     return
   }
 
-  // All other requests: SSR.
-  await handler(req, res)
+  // All other requests: SSR (with ISR for routes that declare meta.ssg.revalidate).
+  await isrHandler(req, res)
 }
 `