create-fullstack-scaffold 0.5.6 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fullstack-scaffold",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "type": "module",
   "bin": {
     "create-fullstack-scaffold": "dist/cli/index.js"

package/template/package.json

@@ -1,7 +1,7 @@
 {
   "name": "biomimic-todo-app",
   "private": true,
-  "version": "0.5.6",
+  "version": "0.5.7",
   "type": "module",
   "bin": {
     "biomimic": "./dist/cli/index.js"
@@ -105,10 +105,6 @@
     "@eslint/js": "^9.39.4",
     "@hono/vite-dev-server": "^0.23.0",
     "@playwright/test": "^1.60.0",
-    "@prerenderer/renderer-jsdom": "^1.1.9",
-    "@prerenderer/renderer-puppeteer": "^1.2.4",
-    "puppeteer": "^24.43.1",
-    "@prerenderer/rollup-plugin": "^0.3.12",
     "@tailwindcss/postcss": "^4.2.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.8.0",

package/template/src/client/entry-server.tsx

@@ -50,6 +50,11 @@ export function renderSSR(pathname: string, data: SSRData): SSRRenderResult {
   // 4. Render with helmet context to extract head tags
   const helmetContext: Record<string, unknown> = {}
 
+  // 服务端把 ISR 数据挂到 globalThis：组件的 ssrInitial*() 在 renderToString
+  // 期间与浏览器水合同源读取（globalThis === window），首帧即渲染真实内容
+  const globalData = globalThis as { __SSR_DATA__?: unknown }
+  globalData.__SSR_DATA__ = data
+
   try {
     // 页面级 SSR：ISR 路由有静态同构组件（ssr-pages）——渲染真实页面
     // 内容而非 lazy Loading 壳（SEO 核心）；其余路由回退 AppRoutes 壳。
@@ -78,7 +83,8 @@ export function renderSSR(pathname: string, data: SSRData): SSRRenderResult {
 
     return { html, helmet: { title: titleStr, meta: metaStr } }
   } finally {
-    // 6. Restore store state
+    // 6. Restore store state + 清理服务端数据挂载（防跨请求泄漏）
     restoreEntryStores(snapshot)
+    delete globalData.__SSR_DATA__
   }
 }

package/template/src/client/main.tsx

@@ -85,11 +85,3 @@ if (hasSsrMarkup) {
     </React.StrictMode>
   )
 }
-
-if (typeof window !== 'undefined') {
-  requestAnimationFrame(() => {
-    setTimeout(() => {
-      document.dispatchEvent(new CustomEvent('prerender-ready'))
-    }, 100)
-  })
-}

package/template/src/client/pages/ContentDetailPage.tsx

@@ -7,7 +7,7 @@ import { apiClient } from '@client/services/apiClient'
 // SSR 首帧数据：ISR 服务端写入 __SSR_DATA__.content（详情页按 id 匹配）
 function ssrInitialContent(id?: string): Content | null {
   try {
-    const d = (window as unknown as { __SSR_DATA__?: { content?: Content | null } }).__SSR_DATA__
+    const d = (globalThis as { __SSR_DATA__?: { content?: Content | null } }).__SSR_DATA__
     const c = d?.content ?? null
     return c && (!id || c.id === id) ? c : null
   } catch {

package/template/src/client/pages/ContentListPage.tsx

@@ -17,7 +17,7 @@ const CATEGORIES: { value: ContentCategory | ''; label: string }[] = [
 // 直接用它渲染（水合一致、爬虫可见真实内容），effect 再刷新
 function ssrInitialContents(): Content[] {
   try {
-    const d = (window as unknown as { __SSR_DATA__?: { contents?: Content[] } }).__SSR_DATA__
+    const d = (globalThis as { __SSR_DATA__?: { contents?: Content[] } }).__SSR_DATA__
     return d?.contents ?? []
   } catch {
     return []

package/template/src/client/pages/TodoPage.tsx

@@ -22,6 +22,19 @@ import type { Todo } from '@shared/schemas'
 
 type FilterType = 'all' | 'pending' | 'in_progress' | 'completed'
 
+// SSR 首帧数据：ISR 管线把 registry fetch 的数据写进 __SSR_DATA__，
+// 服务端 renderToString 与浏览器水合从同一 globalThis 读取。zustand v5 的
+// 服务端快照固定为 getInitialState（setState 种子对 SSR 不可见），首帧
+// 列表必须从这里兜底，挂载后 effect 再走 store 刷新
+function ssrInitialTodos(): Todo[] {
+  try {
+    const d = (globalThis as { __SSR_DATA__?: { todos?: Todo[] } }).__SSR_DATA__
+    return d?.todos ?? []
+  } catch {
+    return []
+  }
+}
+
 export const TodoPage: React.FC = () => {
   const todos = useTodoStore(state => state.todos)
   const loading = useTodoStore(state => state.loading)
@@ -37,6 +50,9 @@ export const TodoPage: React.FC = () => {
 
   const [newTodoTitle, setNewTodoTitle] = useState('')
   const [newTodoDescription, setNewTodoDescription] = useState('')
+  const [ssrTodos] = useState<Todo[]>(ssrInitialTodos)
+  // store 一旦有数据（挂载后 fetch 完成）即以 store 为准，首帧用 SSR 数据兜底
+  const visibleTodos = todos.length > 0 ? todos : ssrTodos
   const [filter, setFilter] = useState<FilterType>('all')
   const [expandedTodoId, setExpandedTodoId] = useState<number | null>(null)
   const fileInputRefs = useRef<Map<number, HTMLInputElement>>(new Map())
@@ -95,7 +111,7 @@ export const TodoPage: React.FC = () => {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
   }
 
-  const filteredTodos = todos.filter(todo => {
+  const filteredTodos = visibleTodos.filter(todo => {
     if (filter === 'all') return true
     return todo.status === filter
   })
@@ -174,17 +190,17 @@ export const TodoPage: React.FC = () => {
         </div>
       )}
 
-      {loading && todos.length === 0 && (
+      {loading && visibleTodos.length === 0 && (
         <div className="flex items-center justify-center py-12" data-testid="loading-indicator">
           <LoadingSpinner size="lg" />
         </div>
       )}
 
-      {todos.length > 0 && (
+      {visibleTodos.length > 0 && (
         <div className="mb-6 flex items-center justify-between">
           <div className="flex items-center gap-2" data-testid="todo-count">
             <span className="text-sm text-gray-500">Total:</span>
-            <span className="text-sm font-medium text-gray-900">{todos.length}</span>
+            <span className="text-sm font-medium text-gray-900">{visibleTodos.length}</span>
           </div>
           <div className="flex items-center gap-2">
             <button

package/template/src/client/ssr-pages.ts

@@ -1,20 +1,11 @@
 /**
- * SSR 静态页面注册表（替代 preset-ui-config 的 lazy 组件用于服务端渲染）。
+ * SSR 静态页面注册表（模板全量版；CLI 按 preset 重新生成，只导入实际存在的页面）。
  *
- * 为什么需要它：renderToString 是同步的，解析不了 React.lazy 的动态
- * import——直接用 preset-ui-config 会让 SSR body 永远是 Suspense 的
- * Loading 壳。这里用静态 import 提供同构组件映射，页面内容在服务端
- * 真正渲染进 HTML（ISR/SEO 的核心价值所在）。
- *
- * 客户端不走这里（CSR 仍用 lazy 代码分割），水合由 entry-server 渲染的
- * HTML + main.tsx 的 hydrateRoot 完成——两侧组件树来自同一源码，静态
- * 导入版多打一份包只进 server bundle（tsup 的 CF 构建），不影响 client
- * chunk 体积。
+ * renderToString 解析不了 React.lazy——ISR 路由的页面级 SSR 依赖这里的
+ * 静态同构组件，页面内容才真正渲染进 HTML（SEO/首屏的核心价值）。
  */
 
 import type { ComponentType } from 'react'
-
-// 按需静态导入 ISR 场景的页面（内容型、需要 SEO 的页面）
 import { TodoPage } from './pages/TodoPage'
 import { ContentListPage } from './pages/ContentListPage'
 import { ContentDetailPage } from './pages/ContentDetailPage'
@@ -22,11 +13,6 @@ import { TopicsPage } from './pages/TopicsPage'
 
 export type SsrPageComponent = ComponentType
 
-/**
- * 路由 → 同构组件映射。
- * 未列出的路由（管理后台、登录页等）SSR 输出布局壳——它们本来就不
- * 需要 SEO（登录后才可见），客户端 lazy 照常工作。
- */
 export const SSR_PAGES: Record<string, SsrPageComponent> = {
   '/todos': TodoPage,
   '/content': ContentListPage,
@@ -34,11 +20,14 @@ export const SSR_PAGES: Record<string, SsrPageComponent> = {
   '/topics': TopicsPage,
 }
 
-/** ISR 路径是否有关联的静态组件（决定 body 渲染还是仅 meta） */
+const SSR_PATTERNS: Array<{ prefix: string; component: SsrPageComponent }> = [
+  { prefix: '/content/', component: ContentDetailPage },
+]
+
 export function getSsrPage(pathname: string): SsrPageComponent | null {
   if (SSR_PAGES[pathname]) return SSR_PAGES[pathname]
-  // 详情页模式 /content/123
-  const m = pathname.match(/^\/content\/[^/]+$/)
-  if (m) return SSR_PAGES['/content/:id']
+  for (const p of SSR_PATTERNS) {
+    if (pathname.startsWith(p.prefix)) return p.component
+  }
   return null
 }

package/template/src/server/entries/node.ts

@@ -1,5 +1,5 @@
 /**
- * @framework-baseline 159d5e23f19e9793
+ * @framework-baseline 91c7b6f83b7c9913
  * @framework-modify
  * @reason 添加 SPA 前端路由处理，区分开发/生产环境
  * @impact 新增前端路由处理逻辑，/admin/* 返回 admin.html，其他路由返回 index.html
@@ -17,22 +17,10 @@ import { logger } from '../utils/logger'
 import { createApp } from '../app'
 import { getDb, runMigrations } from '../db'
 import { createISRCache, isISRRoute } from '@server/core/isr-cache'
+// Side-effect: 注册 ISR 路由到全局 registry（Node 入口此前漏了这一行——
+// registry 空 → isISRRoute 恒 false → ISR 永远不触发，SSR 壳照旧）
+import '@server/isr-modules'
 import { renderISRPage } from '@server/core/isr-renderer'
-// @client/entry-server 仅含 client 的 preset 存在；cli-only 会因静态
-// 导入悬空（verify 链已拦过一次）。运行时按需加载，缺省回退壳渲染。
-type RenderSSRFn = (pathname: string, data: never) => { html: string }
-
-async function loadRenderSSR(): Promise<RenderSSRFn | null> {
-  try {
-    // 变量说明符：tsc 不做模块解析（cli-only 无 client 目录时字面量
-    // 动态导入也会被 tsc 拦——与 vitest.config 的 react 插件同法）
-    const mod = '@client/entry-server'
-    const m = (await import(/* @vite-ignore */ mod)) as { renderSSR: RenderSSRFn }
-    return m.renderSSR
-  } catch {
-    return null
-  }
-}
 import { isrRegistry, type ISRRouterContext } from '@server/core/isr-registry'
 import { setISRCache } from '@server/core/isr-invalidation'
 import { setRuntimeAdapter } from '@server/core/runtime'
@@ -217,9 +205,28 @@ export async function createServer() {
  * 页面级渲染 → renderISRPage 注入 body + meta + __SSR_DATA__。
  * 返回 null 表示无注册路由/渲染失败，调用方回退 SPA index.html。
  */
+type SSRRenderer = (pathname: string, data: unknown) => { html: string } | null
+
+// 渲染桥按需加载：静态 import 会把整个 React SSR 图（react-router-dom 等
+// CJS 依赖）拉进 vite dev 的 SSR 模块图，dev server 全路由 500；动态加载
+// 只在生产渲染 ISR 路由时触发，dev 下失败则回退 SPA 壳。
+let cachedRenderer: SSRRenderer | null | undefined
+async function loadSSRRenderer(): Promise<SSRRenderer | null> {
+  if (cachedRenderer !== undefined) return cachedRenderer
+  try {
+    const mod = await import('@server/ssr-bridge')
+    cachedRenderer = mod.renderSSR
+  } catch {
+    cachedRenderer = null
+  }
+  return cachedRenderer
+}
+
 async function renderISRForRoute(pathname: string): Promise<string | null> {
   const entry = isrRegistry.match(pathname)
   if (!entry) return null
+  const renderSSR = await loadSSRRenderer()
+  if (!renderSSR) return null // 无 client 的 preset（cli-only 等）回退 SPA 壳
   const ctx: ISRRouterContext = { db: await getDb(), env: {} }
   let data: unknown = {}
   let meta = { title: 'App', description: '' }
@@ -229,10 +236,9 @@ async function renderISRForRoute(pathname: string): Promise<string | null> {
   } catch {
     // DB 错误——回退默认 meta 继续渲染壳
   }
-  const renderSSR = await loadRenderSSR()
-  if (!renderSSR) return null // 无 client（cli-only 等）——调用方回退 SPA
   try {
-    const ssr = renderSSR(pathname, data as never)
+    const ssr = renderSSR(pathname, data)
+    if (!ssr) return null // 渲染桥返回 null（无 client 变体）
     return renderISRPage({ template: indexHtml, body: ssr.html, meta, data })
   } catch (e) {
     console.warn('ISR render failed:', e)

package/template/src/server/ssr-bridge.ts

@@ -0,0 +1,10 @@
+/**
+ * SSR 渲染桥（本文件在模板中为全量版；CLI 脚手架时按 preset 重新生成：
+ * cli-only 等无 client 的 preset 导出 null，避免悬空导入）。
+ */
+import { renderSSR as renderSSRImpl } from '@client/entry-server'
+
+// data 由 ISR registry fetch 提供（形状随模块而异），renderSSR 内部自取所需字段
+export function renderSSR(pathname: string, data: unknown): { html: string } {
+  return renderSSRImpl(pathname, data as Parameters<typeof renderSSRImpl>[1])
+}

package/template/vite.config.ts

@@ -1,5 +1,4 @@
 import path from 'path'
-import { existsSync } from 'fs'
 import { defineConfig, type Plugin } from 'vite'
 import devServer from '@hono/vite-dev-server'
 import { websocketPlugin, dbPlugin } from './vite-plugins'
@@ -20,64 +19,9 @@ if (process.env.ANALYZE === 'true') {
     // rollup-plugin-visualizer not installed — run: npm install -D rollup-plugin-visualizer
   }
 }
-// Prerender is optional — only needed during production build with puppeteer + Chrome installed
-let prerender: typeof import('@prerenderer/rollup-plugin').default | undefined
-let puppeteerRenderer: typeof import('@prerenderer/renderer-puppeteer').default | undefined
-try {
-  const prerenderMod = await import('@prerenderer/rollup-plugin')
-  prerender = prerenderMod.default
-  const rendererMod = await import('@prerenderer/renderer-puppeteer')
-  puppeteerRenderer = rendererMod.default
-  // Verify Chrome is actually available at runtime
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-ignore — puppeteer is an optional dependency, may not be installed
-  const pupMod = await import('puppeteer')
-  const chromePath: string = await pupMod.executablePath()
-  if (!existsSync(chromePath)) {
-    prerender = undefined
-    puppeteerRenderer = undefined
-  }
-} catch {
-  // puppeteer/Chrome not available — prerendering disabled
-}
-
-async function getPrerenderRoutes(): Promise<string[]> {
-  const staticRoutes = ['/', '/todos', '/notifications', '/websocket', '/content']
-
-  try {
-    const { createClient } = await import('@libsql/client')
-    const dbCandidates = [
-      path.resolve(process.cwd(), 'data/production.db'),
-      path.resolve(process.cwd(), 'data/app.db'),
-      path.resolve(process.cwd(), 'data/development.db'),
-    ]
-
-    for (const dbPath of dbCandidates) {
-      if (!existsSync(dbPath)) continue
-
-      const client = createClient({ url: `file:${dbPath}` })
-      try {
-        const rs = await client.execute(
-          "SELECT id FROM contents WHERE status = 'published' ORDER BY created_at DESC"
-        )
-        client.close()
-
-        if (rs.rows.length > 0) {
-          const contentRoutes = rs.rows.map(row => `/content/content-${row.id}`)
-          return [...staticRoutes, ...contentRoutes]
-        }
-      } catch {
-        client.close()
-      }
-    }
-  } catch {
-    // fallback
-  }
-
-  return staticRoutes
-}
-
-const routes = await getPrerenderRoutes()
+// 说明：构建期 puppeteer 预渲染已移除——ISR 运行时管线（registry fetch +
+// renderSSR + __SSR_DATA__ 注入）在请求时产出新鲜 HTML，构建期快照反而会
+// 以空数据/错误文本固化页面并在 serveStatic 下遮蔽运行时 ISR。
 
 export default defineConfig({
   server: {
@@ -117,20 +61,7 @@ export default defineConfig({
           'vendor-hono': ['hono'],
           'vendor-zustand': ['zustand'],
         },
-        plugins: [
-          ...(prerender && puppeteerRenderer
-            ? [
-                prerender({
-                  routes,
-                  renderer: new puppeteerRenderer({
-                    renderAfterDocumentEvent: 'prerender-ready',
-                    renderAfterTime: 5000,
-                  }),
-                }),
-              ]
-            : []),
-          ...(visualizerPlugin ? [visualizerPlugin()] : []),
-        ],
+        plugins: [...(visualizerPlugin ? [visualizerPlugin()] : [])],
       },
       onwarn(warning, defaultHandler) {
         // Suppress antd "use client" directive warnings (React Server Components marker)