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

@jasonshimmy/vite-plugin-cer-app 0.5.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 (61) hide show

package/CHANGELOG.md +8 -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/cli/create/templates/spa/package.json.tpl +2 -2
package/dist/cli/create/templates/ssg/package.json.tpl +2 -2
package/dist/cli/create/templates/ssr/package.json.tpl +2 -2
package/dist/plugin/build-ssg.d.ts.map +1 -1
package/dist/plugin/build-ssg.js +17 -3
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 +2 -2
package/dist/runtime/entry-server-template.d.ts.map +1 -1
package/dist/runtime/entry-server-template.js +57 -19
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 +66 -5
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 +7 -3
package/src/__tests__/cli/preview-isr.test.ts +44 -0
package/src/__tests__/plugin/build-ssg-render.test.ts +46 -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 +76 -5
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/cli/create/templates/spa/package.json.tpl +2 -2
package/src/cli/create/templates/ssg/package.json.tpl +2 -2
package/src/cli/create/templates/ssr/package.json.tpl +2 -2
package/src/plugin/build-ssg.ts +15 -3
package/src/plugin/dev-server.ts +33 -0
package/src/plugin/virtual/routes.ts +24 -2
package/src/runtime/entry-server-template.ts +57 -19
package/src/runtime/isr-handler.ts +183 -0
package/src/types/page.ts +14 -0

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

@@ -7,7 +7,7 @@
  *
  * Key features:
  * - AsyncLocalStorage for race-condition-free concurrent renders (SSG concurrency > 1)
- * - Declarative Shadow DOM via renderToStringWithJITCSSDSD (always on)
+ * - Declarative Shadow DOM via renderToStreamWithJITCSSDSD (always on, streamed)
  * - useHead() support via beginHeadCollection / endHeadCollection
  * - DSD polyfill injected at end of <body> after client-template merge
  */
@@ -23,10 +23,12 @@ import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
 import { runtimeConfig } from 'virtual:cer-app-config'
 import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
-import { registerEntityMap, renderToStringWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
+import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 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,49 +184,75 @@ 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,
+    // so ALL useHead() calls happen before the stream object is returned. We must
+    // call endHeadCollection() immediately — before any await — to avoid a race
+    // window where a concurrent request (e.g. SSG concurrency > 1) resets the
+    // shared globalThis collector while this handler is suspended at an await.
     beginHeadCollection()
     // dsdPolyfill: false — we inject the polyfill manually after merging so it
     // lands at the end of <body>, not inside <cer-layout-view> light DOM where
     // scripts may not execute.
-    const { htmlWithStyles } = renderToStringWithJITCSSDSD(vnode, {
-      dsdPolyfill: false,
-      router,
-    })
+    // The first chunk from the stream is the full synchronous render. Subsequent
+    // chunks are async component swap scripts streamed as they resolve.
+    const stream = renderToStreamWithJITCSSDSD(vnode, { dsdPolyfill: false, router })
-    // Collect and serialize any useHead() calls from the rendered components.
+    // Collect head tags synchronously — all useHead() calls have already fired
+    // inside the stream constructor's start() before it returned.
     const headTags = serializeHeadTags(endHeadCollection())
+    const reader = stream.getReader()
+    // Read the first (synchronous) chunk.
+    const { value: firstChunk = '' } = await reader.read()
     // Merge loader data script + useHead() tags into the document head.
     const headContent = [head, headTags].filter(Boolean).join('\\n')
     // Wrap the rendered body in a full HTML document and inject the head additions
     // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.
-    const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${htmlWithStyles}</body></html>\`
+    const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${firstChunk}</body></html>\`
-    let finalHtml = _clientTemplate
+    const merged = _clientTemplate
       ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)
       : ssrHtml
-    // Inject DSD polyfill at end of <body>, outside <cer-layout-view>, so the
-    // browser runs it after parsing the declarative shadow roots.
-    finalHtml = finalHtml.includes('</body>')
-      ? finalHtml.replace('</body>', DSD_POLYFILL_SCRIPT + '</body>')
-      : finalHtml + DSD_POLYFILL_SCRIPT
+    // Split at </body> so async swap scripts and the DSD polyfill can be streamed
+    // in before the document is closed.
+    const bodyCloseIdx = merged.lastIndexOf('</body>')
+    const beforeBodyClose = bodyCloseIdx >= 0 ? merged.slice(0, bodyCloseIdx) : merged
+    const fromBodyClose  = bodyCloseIdx >= 0 ? merged.slice(bodyCloseIdx) : ''
     res.setHeader('Content-Type', 'text/html; charset=utf-8')
-    res.end(finalHtml)
+    res.setHeader('Transfer-Encoding', 'chunked')
+    res.write(beforeBodyClose)
+    // Stream async component swap scripts through as-is.
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      res.write(value)
+    }
+    // Inject DSD polyfill immediately before </body>, then close the document.
+    res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)
   })
 }
+// 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
 `

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

@@ -0,0 +1,183 @@
+/**
+ * createIsrHandler — portable stale-while-revalidate ISR factory.
+ *
+ * Wraps any Express-compatible SSR handler with an in-memory ISR cache.
+ * Routes that export `meta.ssg.revalidate` get cached for the declared TTL.
+ *
+ * Usage (Express):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use(createIsrHandler(routes, handler))
+ *
+ * Usage (Hono):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use('*', createIsrHandler(routes, handler))
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+export interface IsrCacheEntry {
+  html: string
+  headers: Record<string, string>
+  statusCode: number
+  builtAt: number
+  revalidate: number
+  revalidating: boolean
+}
+export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => unknown
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function _matchPattern(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))
+}
+function _findRevalidate(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  urlPath: string,
+): number | null {
+  for (const route of routes) {
+    if (_matchPattern(route.path, urlPath)) {
+      const ssg = route.meta?.ssg as Record<string, unknown> | undefined
+      if (typeof ssg?.revalidate === 'number') return ssg.revalidate
+      return null
+    }
+  }
+  return null
+}
+async function _renderForCache(
+  urlPath: string,
+  handler: SsrHandlerFn,
+  revalidate: number,
+): Promise<IsrCacheEntry | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = []
+    const capturedHeaders: Record<string, string | string[]> = {}
+    let capturedStatus = 200
+    const fakeRes = {
+      get statusCode() { return capturedStatus },
+      set statusCode(v: number) { capturedStatus = v },
+      setHeader(name: string, value: string | string[]) {
+        capturedHeaders[name.toLowerCase()] = value
+      },
+      write(chunk: string | Buffer) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf-8'))
+      },
+      end(body?: string | Buffer) {
+        if (body !== undefined) {
+          chunks.push(Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf-8'))
+        }
+        resolve({
+          html: Buffer.concat(chunks).toString('utf-8'),
+          headers: Object.fromEntries(
+            Object.entries(capturedHeaders).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : v]),
+          ),
+          statusCode: capturedStatus,
+          builtAt: Date.now(),
+          revalidate,
+          revalidating: false,
+        })
+      },
+    } as unknown as ServerResponse
+    const fakeReq = {
+      url: urlPath,
+      method: 'GET',
+      headers: { accept: 'text/html' },
+    } as IncomingMessage
+    try {
+      const result = handler(fakeReq, fakeRes)
+      if (result && typeof (result as Promise<void>).catch === 'function') {
+        ;(result as Promise<void>).catch(() => resolve(null))
+      }
+    } catch {
+      resolve(null)
+    }
+  })
+}
+function _serveFromCache(entry: IsrCacheEntry, res: ServerResponse, status: 'HIT' | 'STALE'): void {
+  res.statusCode = entry.statusCode
+  for (const [name, value] of Object.entries(entry.headers)) {
+    res.setHeader(name, value)
+  }
+  res.setHeader('X-Cache', status)
+  res.end(entry.html)
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Wraps an SSR handler with stale-while-revalidate ISR caching.
+ *
+ * Routes that declare `meta.ssg.revalidate` in the `routes` array are cached
+ * in memory. After the TTL expires the stale response is served immediately
+ * while a fresh render runs in the background (stale-while-revalidate).
+ *
+ * Routes without a `revalidate` value are passed through to the handler directly.
+ */
+export function createIsrHandler(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  handler: SsrHandlerFn,
+): SsrHandlerFn {
+  const cache = new Map<string, IsrCacheEntry>()
+  return async (req: IncomingMessage, res: ServerResponse): Promise<unknown> => {
+    const urlPath = (req.url ?? '/').split('?')[0]
+    const revalidate = _findRevalidate(routes, urlPath)
+    if (revalidate === null) {
+      return handler(req, res)
+    }
+    const cached = cache.get(urlPath)
+    const now = Date.now()
+    if (cached) {
+      const ageSeconds = (now - cached.builtAt) / 1000
+      if (ageSeconds < cached.revalidate) {
+        _serveFromCache(cached, res, 'HIT')
+        return
+      }
+      if (!cached.revalidating) {
+        cached.revalidating = true
+        _serveFromCache(cached, res, 'STALE')
+        const timeout = setTimeout(() => { if (cached) cached.revalidating = false }, 30_000)
+        _renderForCache(urlPath, handler, revalidate).then((entry) => {
+          clearTimeout(timeout)
+          if (entry) cache.set(urlPath, entry)
+          else if (cached) cached.revalidating = false
+        }).catch(() => {
+          clearTimeout(timeout)
+          if (cached) cached.revalidating = false
+        })
+        return
+      }
+      _serveFromCache(cached, res, 'STALE')
+      return
+    }
+    // Cache miss — render, cache, then serve.
+    const entry = await _renderForCache(urlPath, handler, revalidate)
+    if (entry) {
+      cache.set(urlPath, entry)
+      _serveFromCache(entry, res, 'HIT')
+    } else {
+      await handler(req, res)
+    }
+  }
+}

package/src/types/page.ts CHANGED Viewed

@@ -32,6 +32,20 @@ export interface PageMeta {
    * @example export const meta = { transition: 'fade' }
    */
   transition?: string | boolean
+  /**
+   * Per-route rendering strategy. Overrides the global `mode` for this route.
+   *
+   * - `'server'` — always render server-side, never pre-render. In SSG mode
+   *   the route is skipped during the static build.
+   * - `'static'` — always serve pre-rendered static HTML. In the SSR preview
+   *   server the pre-rendered file is served from disk; falls back to SSR if
+   *   not found.
+   * - `'spa'`    — client-only. In SSR mode the server returns the SPA shell
+   *   (index.html) without rendering. In SSG mode the route is skipped.
+   *
+   * @example export const meta = { render: 'server' }
+   */
+  render?: 'static' | 'server' | 'spa'
 }
 export interface PageLoaderContext<P extends Record<string, string> = Record<string, string>> {