create-fullstack-scaffold 0.5.2 → 0.5.6

package/package.json

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

package/template/eslint.config.js

@@ -114,6 +114,7 @@ export default tseslint.config(
   },
   {
     files: ['src/server/**/*.ts'],
+    ignores: ['src/server/route-registry.ts'],
     rules: {
       'no-console': 'error',
       'local-rules/require-hono-chain-syntax': 'error',
@@ -128,7 +129,9 @@ export default tseslint.config(
       'local-rules/no-new-old-service-naming': 'error',
       'local-rules/no-cross-module-service-import': 'error',
       'local-rules/route-location': 'error',
-      'local-rules/limit-type-complexity': ['warn', { maxRouteChainLength: 15 }],
+      // TS2589 防线收紧：类型出口已由 no-merged-api-type-export 封死，
+      // 链长阈值从 warn/15 收紧到 error/5（超出即架构回归信号）
+      'local-rules/limit-type-complexity': ['error', { maxRouteChainLength: 5 }],
       'local-rules/no-merged-api-type-export': 'error',
     },
   },

package/template/package.json

@@ -1,7 +1,7 @@
 {
   "name": "biomimic-todo-app",
   "private": true,
-  "version": "0.5.2",
+  "version": "0.5.6",
   "type": "module",
   "bin": {
     "biomimic": "./dist/cli/index.js"

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

@@ -1,5 +1,5 @@
 /**
- * @framework-baseline 1a361bf1bb0e5343
+ * @framework-baseline 00b6a72a77e03864
  */
 
 /**
@@ -17,6 +17,7 @@ import { StaticRouter } from 'react-router-dom'
 import { HelmetProvider } from 'react-helmet-async'
 
 import { AppRoutes } from './AppRoutes'
+import { getSsrPage } from './ssr-pages'
 import {
   snapshotEntryStores,
   seedEntryStores,
@@ -50,17 +51,25 @@ export function renderSSR(pathname: string, data: SSRData): SSRRenderResult {
   const helmetContext: Record<string, unknown> = {}
 
   try {
-    const html = renderToString(
-      React.createElement(
-        HelmetProvider,
-        { context: helmetContext },
-        React.createElement(
-          StaticRouter,
-          { location: pathname },
-          React.createElement(AppRoutes, { presetId: preset })
+    // 页面级 SSR：ISR 路由有静态同构组件（ssr-pages）——渲染真实页面
+    // 内容而非 lazy Loading 壳（SEO 核心）；其余路由回退 AppRoutes 壳。
+    const SsrPage = getSsrPage(pathname)
+    const body = SsrPage
+      ? React.createElement(
+          HelmetProvider,
+          { context: helmetContext },
+          React.createElement(StaticRouter, { location: pathname }, React.createElement(SsrPage))
         )
-      )
-    )
+      : React.createElement(
+          HelmetProvider,
+          { context: helmetContext },
+          React.createElement(
+            StaticRouter,
+            { location: pathname },
+            React.createElement(AppRoutes, { presetId: preset })
+          )
+        )
+    const html = renderToString(body)
 
     // 5. Extract helmet data
     const helmet = (helmetContext as { helmet?: Record<string, unknown> }).helmet || {}

package/template/src/client/main.tsx

@@ -67,11 +67,24 @@ const RootApp = () => {
   )
 }
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <RootApp />
-  </React.StrictMode>
-)
+// 水合：SSR（ISR 管线）已输出 #root 内的 HTML——hydrateRoot 复用而非
+// 重画（SEO/首屏收益成立的前提）。无 SSR 的普通访问 fallback createRoot。
+const rootEl = document.getElementById('root')!
+const hasSsrMarkup = rootEl.hasChildNodes()
+if (hasSsrMarkup) {
+  ReactDOM.hydrateRoot(
+    rootEl,
+    <React.StrictMode>
+      <RootApp />
+    </React.StrictMode>
+  )
+} else {
+  ReactDOM.createRoot(rootEl).render(
+    <React.StrictMode>
+      <RootApp />
+    </React.StrictMode>
+  )
+}
 
 if (typeof window !== 'undefined') {
   requestAnimationFrame(() => {

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

@@ -4,10 +4,21 @@ import { Helmet } from 'react-helmet-async'
 import type { Content } from '@shared/modules/content'
 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 c = d?.content ?? null
+    return c && (!id || c.id === id) ? c : null
+  } catch {
+    return null
+  }
+}
+
 export const ContentDetailPage: React.FC = () => {
   const { id } = useParams<{ id: string }>()
-  const [content, setContent] = useState<Content | null>(null)
-  const [loading, setLoading] = useState(true)
+  const [content, setContent] = useState<Content | null>(() => ssrInitialContent(id))
+  const [loading, setLoading] = useState(() => ssrInitialContent(id) === null)
   const [error, setError] = useState<string | null>(null)
 
   const fetchContent = useCallback(async (contentId: string) => {

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

@@ -13,9 +13,20 @@ const CATEGORIES: { value: ContentCategory | ''; label: string }[] = [
   { value: 'policy', label: '政策' },
 ]
 
+// SSR 首帧数据：ISR 管线在服务端把数据写进 __SSR_DATA__，客户端首帧
+// 直接用它渲染（水合一致、爬虫可见真实内容），effect 再刷新
+function ssrInitialContents(): Content[] {
+  try {
+    const d = (window as unknown as { __SSR_DATA__?: { contents?: Content[] } }).__SSR_DATA__
+    return d?.contents ?? []
+  } catch {
+    return []
+  }
+}
+
 export const ContentListPage: React.FC = () => {
-  const [contents, setContents] = useState<Content[]>([])
-  const [loading, setLoading] = useState(true)
+  const [contents, setContents] = useState<Content[]>(ssrInitialContents)
+  const [loading, setLoading] = useState(ssrInitialContents().length === 0)
   const [error, setError] = useState<string | null>(null)
   const [category, setCategory] = useState<ContentCategory | ''>('')
   const [search, setSearch] = useState('')

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

@@ -0,0 +1,44 @@
+/**
+ * SSR 静态页面注册表（替代 preset-ui-config 的 lazy 组件用于服务端渲染）。
+ *
+ * 为什么需要它：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 体积。
+ */
+
+import type { ComponentType } from 'react'
+
+// 按需静态导入 ISR 场景的页面（内容型、需要 SEO 的页面）
+import { TodoPage } from './pages/TodoPage'
+import { ContentListPage } from './pages/ContentListPage'
+import { ContentDetailPage } from './pages/ContentDetailPage'
+import { TopicsPage } from './pages/TopicsPage'
+
+export type SsrPageComponent = ComponentType
+
+/**
+ * 路由 → 同构组件映射。
+ * 未列出的路由（管理后台、登录页等）SSR 输出布局壳——它们本来就不
+ * 需要 SEO（登录后才可见），客户端 lazy 照常工作。
+ */
+export const SSR_PAGES: Record<string, SsrPageComponent> = {
+  '/todos': TodoPage,
+  '/content': ContentListPage,
+  '/content/:id': ContentDetailPage,
+  '/topics': TopicsPage,
+}
+
+/** ISR 路径是否有关联的静态组件（决定 body 渲染还是仅 meta） */
+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']
+  return null
+}

package/template/src/client/stores/entry-stores.ts

@@ -12,6 +12,9 @@ import type { Todo } from '@shared/schemas'
 
 export interface SSRData {
   todos?: Todo[]
+  /** content 模块 ISR 数据（列表/详情首帧，页面从 __SSR_DATA__ 读取） */
+  contents?: unknown[]
+  content?: Record<string, unknown> | null
   [key: string]: unknown
 }
 

package/template/src/server/core/isr-renderer.ts

@@ -1,5 +1,5 @@
 /**
- * @framework-baseline cec621fae360ba2b
+ * @framework-baseline 108b720f9d939fcd
  *
  *
  * @framework-modify
@@ -32,6 +32,8 @@ export interface ISRRenderOptions {
   body?: string
   /** Meta tags */
   meta: ISRPageMeta
+  /** ISR 抓取数据：序列化进 window.__SSR_DATA__ 供客户端首帧渲染（水合一致） */
+  data?: unknown
 }
 
 /**
@@ -39,7 +41,7 @@ export interface ISRRenderOptions {
  * If template is null, generates a minimal standalone HTML.
  */
 export function renderISRPage(opts: ISRRenderOptions): string {
-  const { template, body = '', meta } = opts
+  const { template, body = '', meta, data } = opts
   const safeTitle = escapeHtml(meta.title)
   const safeDesc = escapeHtml(meta.description)
 
@@ -54,6 +56,10 @@ export function renderISRPage(opts: ISRRenderOptions): string {
       `    <meta name="description" content="${safeDesc}" />\n    <meta property="og:title" content="${safeTitle}" />\n    <meta property="og:description" content="${safeDesc}" />\n    <meta name="generator" content="ISR-SSG" />\n  </head>`
     )
     html = html.replace('<div id="root"></div>', `<div id="root">${body}</div>`)
+    if (data !== undefined) {
+      const json = JSON.stringify(data).replace(/</g, '\\u003c')
+      html = html.replace('</body>', `<script>window.__SSR_DATA__=${json};</script></body>`)
+    }
     return html
   }
 

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

@@ -1,5 +1,5 @@
 /**
- * @framework-baseline e350401421193896
+ * @framework-baseline e6d62c9969957f22
  * @framework-modify
  * @reason 模块化 ISR 改造 + SSR 渲染：调用 renderSSR 生成 React body，注入到 ISR 模板
  * @impact CF 入口集成 React SSR，ISR 同时负责 SEO meta 标签和 body 渲染
@@ -212,7 +212,7 @@ async function renderISRForRoute(
     // Fallback: empty body, SPA will hydrate
   }
 
-  return renderISRPage({ template: cachedTemplate, body, meta })
+  return renderISRPage({ template: cachedTemplate, body, meta, data })
 }
 
 export { isrCache }

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

@@ -17,7 +17,23 @@ import { logger } from '../utils/logger'
 import { createApp } from '../app'
 import { getDb, runMigrations } from '../db'
 import { createISRCache, isISRRoute } from '@server/core/isr-cache'
-import { renderPage } from '@server/core/ssr-renderer'
+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'
 import { getNodeRuntimeAdapter } from '@server/core/runtime-node'
@@ -130,11 +146,13 @@ app.get('*', async c => {
     }
 
     if (result.status === 'stale' && result.html) {
-      renderPage(pathname)
-        .then(rendered => {
-          isrCache.store(pathname, rendered.html).catch(e => {
-            console.warn('ISR cache store (background revalidation) failed:', e)
-          })
+      renderISRForRoute(pathname)
+        .then(html => {
+          if (html) {
+            isrCache.store(pathname, html).catch(e => {
+              console.warn('ISR cache store (background revalidation) failed:', e)
+            })
+          }
         })
         .catch(e => {
           console.warn('ISR background render failed:', e)
@@ -142,11 +160,14 @@ app.get('*', async c => {
       return c.html(result.html)
     }
 
-    const rendered = await renderPage(pathname)
-    isrCache.store(pathname, rendered.html).catch(e => {
-      console.warn('ISR cache store failed:', e)
-    })
-    return c.html(rendered.html)
+    const html = await renderISRForRoute(pathname)
+    if (html) {
+      isrCache.store(pathname, html).catch(e => {
+        console.warn('ISR cache store failed:', e)
+      })
+      return c.html(html)
+    }
+    return c.html(indexHtml)
   }
 
   return c.html(indexHtml)
@@ -191,6 +212,34 @@ export async function createServer() {
   return { server, port: config.port }
 }
 
+/**
+ * 真 ISR 渲染（与 CF 入口同管线）：registry fetch 数据 → renderSSR
+ * 页面级渲染 → renderISRPage 注入 body + meta + __SSR_DATA__。
+ * 返回 null 表示无注册路由/渲染失败，调用方回退 SPA index.html。
+ */
+async function renderISRForRoute(pathname: string): Promise<string | null> {
+  const entry = isrRegistry.match(pathname)
+  if (!entry) return null
+  const ctx: ISRRouterContext = { db: await getDb(), env: {} }
+  let data: unknown = {}
+  let meta = { title: 'App', description: '' }
+  try {
+    data = await entry.fetch(pathname, ctx)
+    meta = entry.meta(data, pathname)
+  } catch {
+    // DB 错误——回退默认 meta 继续渲染壳
+  }
+  const renderSSR = await loadRenderSSR()
+  if (!renderSSR) return null // 无 client（cli-only 等）——调用方回退 SPA
+  try {
+    const ssr = renderSSR(pathname, data as never)
+    return renderISRPage({ template: indexHtml, body: ssr.html, meta, data })
+  } catch (e) {
+    console.warn('ISR render failed:', e)
+    return null
+  }
+}
+
 export async function startServer() {
   const bootstrapLog = logger.bootstrap()