create-fullstack-scaffold 0.5.1 → 0.5.3

package/package.json

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

package/template/drizzle.config.ts

@@ -14,6 +14,8 @@ export default defineConfig({
   out: './drizzle',
   dialect: 'sqlite',
   dbCredentials: {
+    // 与运行时保持同一库文件：drizzle-kit 在无 NODE_ENV 下执行时
+    // config.sqlitePath 会解析为 development.db，这里不能写死 app.db
     url: config.sqlitePath || './data/app.db',
   },
 })

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.1",
+  "version": "0.5.3",
   "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/config.ts

@@ -66,9 +66,7 @@ export function getAppConfig(): AppConfig {
     database: {
       driver: isCloudflare ? 'd1' : dbDriver,
       sqlitePath:
-        typeof process !== 'undefined'
-          ? process.env.SQLITE_PATH || `./data/${nodeEnv}.db`
-          : undefined,
+        typeof process !== 'undefined' ? process.env.SQLITE_PATH || './data/app.db' : undefined,
       mysqlHost: typeof process !== 'undefined' ? process.env.MYSQL_HOST || 'localhost' : undefined,
       mysqlPort:
         typeof process !== 'undefined' ? parseInt(process.env.MYSQL_PORT || '3306', 10) : undefined,

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

@@ -202,7 +202,9 @@ export async function startServer() {
     await initializeDatabase()
     bootstrapLog.info({}, 'Database ready')
   } catch (err) {
-    bootstrapLog.error({ err }, 'Database initialization failed')
+    // pino 走异步 thread-stream transport，process.exit 前不 flush——
+    // 生产致命错误必须同步 console.error，否则静默死（exit 1 零输出）
+    console.error('Database initialization failed:', err)
     process.exit(1)
   }