create-fullstack-scaffold 0.4.25 → 0.5.1

package/template/src/client/App.tsx

@@ -1,46 +1,10 @@
-import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
-import { Layout } from './Layout'
-import { PresetProvider } from './contexts/PresetContext'
-import { getPresetUIConfig, type RouteDef } from './preset-ui-config'
+import { BrowserRouter } from 'react-router-dom'
+import { AppRoutes } from './AppRoutes'
 
 export const App: React.FC<{ presetId?: string }> = ({ presetId = 'todo' }) => {
-  const config = getPresetUIConfig(presetId)
-  const { theme, desktopNav, mobileTabs, defaultRoute, routes, layout, navigation } = config
-
   return (
     <BrowserRouter>
-      <PresetProvider value={presetId}>
-        <Layout
-          preset={presetId}
-          layout={layout}
-          theme={theme}
-          navigation={navigation}
-          desktopNav={desktopNav}
-          mobileTabs={mobileTabs}
-        >
-          <Routes>
-            {defaultRoute !== '/' && (
-              <Route path="/" element={<Navigate to={defaultRoute} replace />} />
-            )}
-            {routes
-              .filter(
-                (r): r is RouteDef & { component: NonNullable<RouteDef['component']> } =>
-                  r.component !== null
-              )
-              .map(route => (
-                <Route key={route.path} path={route.path} element={<route.component />} />
-              ))}
-            <Route
-              path="*"
-              element={
-                <div className="flex items-center justify-center min-h-[50vh] text-gray-400">
-                  404 - Page not found
-                </div>
-              }
-            />
-          </Routes>
-        </Layout>
-      </PresetProvider>
+      <AppRoutes presetId={presetId} />
     </BrowserRouter>
   )
 }

package/template/src/client/AppRoutes.tsx

@@ -0,0 +1,53 @@
+import { Suspense } from 'react'
+import { Routes, Route, Navigate } from 'react-router-dom'
+import { Layout } from './Layout'
+import { PresetProvider } from './contexts/PresetContext'
+import { getPresetUIConfig, type RouteDef } from './preset-ui-config'
+
+export const AppRoutes: React.FC<{ presetId?: string }> = ({ presetId = 'todo' }) => {
+  const config = getPresetUIConfig(presetId)
+  const { theme, desktopNav, mobileTabs, defaultRoute, routes, layout, navigation } = config
+
+  return (
+    <PresetProvider value={presetId}>
+      <Layout
+        preset={presetId}
+        layout={layout}
+        theme={theme}
+        navigation={navigation}
+        desktopNav={desktopNav}
+        mobileTabs={mobileTabs}
+      >
+        <Suspense
+          fallback={
+            <div className="flex items-center justify-center min-h-[50vh] text-gray-400">
+              Loading...
+            </div>
+          }
+        >
+          <Routes>
+            {defaultRoute !== '/' && (
+              <Route path="/" element={<Navigate to={defaultRoute} replace />} />
+            )}
+            {routes
+              .filter(
+                (r): r is RouteDef & { component: NonNullable<RouteDef['component']> } =>
+                  r.component !== null
+              )
+              .map(route => (
+                <Route key={route.path} path={route.path} element={<route.component />} />
+              ))}
+            <Route
+              path="*"
+              element={
+                <div className="flex items-center justify-center min-h-[50vh] text-gray-400">
+                  404 - Page not found
+                </div>
+              }
+            />
+          </Routes>
+        </Suspense>
+      </Layout>
+    </PresetProvider>
+  )
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @framework-baseline 1a361bf1bb0e5343
+ */
+
+/**
+ * SSR Entry Point — used by ISR pipeline to render real React components.
+ *
+ * This module:
+ * 1. Pre-populates Zustand stores with ISR-fetched data (via generated entry-stores)
+ * 2. Renders the app to HTML string via renderToString
+ * 3. Restores stores after render
+ */
+
+import React from 'react'
+import { renderToString } from 'react-dom/server'
+import { StaticRouter } from 'react-router-dom'
+import { HelmetProvider } from 'react-helmet-async'
+
+import { AppRoutes } from './AppRoutes'
+import {
+  snapshotEntryStores,
+  seedEntryStores,
+  restoreEntryStores,
+  type SSRData,
+} from './stores/entry-stores'
+
+interface SSRRenderResult {
+  html: string
+  helmet: {
+    title: string
+    meta: string
+  }
+}
+
+/**
+ * Render the app to HTML string for a given pathname.
+ * Pre-populates stores with ISR data so components render real content.
+ */
+export function renderSSR(pathname: string, data: SSRData): SSRRenderResult {
+  // 1. Snapshot current store state (for cleanup)
+  const snapshot = snapshotEntryStores()
+
+  // 2. Pre-populate stores with ISR data (no-op when preset has no seedable stores)
+  seedEntryStores(data)
+
+  // 3. Set default preset
+  const preset = 'todo'
+
+  // 4. Render with helmet context to extract head tags
+  const helmetContext: Record<string, unknown> = {}
+
+  try {
+    const html = renderToString(
+      React.createElement(
+        HelmetProvider,
+        { context: helmetContext },
+        React.createElement(
+          StaticRouter,
+          { location: pathname },
+          React.createElement(AppRoutes, { presetId: preset })
+        )
+      )
+    )
+
+    // 5. Extract helmet data
+    const helmet = (helmetContext as { helmet?: Record<string, unknown> }).helmet || {}
+    const titleStr = helmet.title?.toString() || ''
+    const metaStr = helmet.meta?.toString() || ''
+
+    return { html, helmet: { title: titleStr, meta: metaStr } }
+  } finally {
+    // 6. Restore store state
+    restoreEntryStores(snapshot)
+  }
+}

package/template/src/client/main.tsx

@@ -7,7 +7,9 @@ import './index.css'
 
 const preset = import.meta.env.VITE_PRESET || 'todo'
 
-if (preset !== 'saas') {
+// Demo 登录令牌：仅供开发服务器开箱体验（e2e 也依赖）；生产构建
+// （import.meta.env.DEV === false）不注入，用户走正常注册/登录
+if (preset !== 'saas' && import.meta.env.DEV) {
   try {
     const raw = localStorage.getItem('auth-token')
     const parsed = raw ? JSON.parse(raw) : null

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

@@ -28,7 +28,7 @@ export const SearchPage: React.FC = () => {
     if (searchQuery) {
       searchPlugins(searchQuery, 1)
     }
-  }, [selectedCategory]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [selectedCategory, searchQuery, searchPlugins])
 
   const handleSearch = (e: FormEvent) => {
     e.preventDefault()

package/template/src/client/services/apiClient.ts

@@ -5,16 +5,20 @@
  * @impact 影响所有客户端 API 请求，需要用户登录后才能访问受保护的接口
  */
 
-import { hc } from 'hono/client'
 import { WSClientImpl } from '@shared/core/ws-client'
 import { SSEClientImpl } from '@shared/core/sse-client'
-import type { ClientApiType } from '@server/index'
+import { createApiFacade } from '@server/rpc-surface'
 
-const baseUrl = import.meta.env.API_BASE_URL || window.location.origin
+const isBrowser = typeof window !== 'undefined'
+
+const baseUrl = isBrowser
+  ? import.meta.env.API_BASE_URL || window.location.origin
+  : 'http://localhost:3010'
 
 const TOKEN_KEY = 'auth-token'
 
 function getAuthToken(): string | null {
+  if (!isBrowser) return null
   try {
     const stored = localStorage.getItem(TOKEN_KEY)
     if (stored) {
@@ -31,6 +35,10 @@ function getAuthToken(): string | null {
 }
 
 const authenticatedFetch = (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+  if (!isBrowser) {
+    return fetch(url, init)
+  }
+
   const token = getAuthToken()
   const headers = new Headers(init?.headers)
 
@@ -54,7 +62,7 @@ const authenticatedFetch = (url: string | URL | Request, init?: RequestInit): Pr
     })
 }
 
-export const apiClient = hc<ClientApiType>(baseUrl, {
+export const apiClient = createApiFacade(baseUrl, {
   fetch: authenticatedFetch as typeof fetch,
   webSocket: url => {
     const token = getAuthToken()

package/template/src/client/stores/__tests__/todoStore.test.ts

@@ -117,7 +117,10 @@ describe('Todo Store', () => {
   describe('fetchTodos', () => {
     it('should fetch todos successfully with array response', async () => {
       const todos = [createMockTodo({ id: 1 }), createMockTodo({ id: 2 })]
-      mockJson.mockResolvedValue({ success: true, data: todos })
+      mockJson.mockResolvedValue({
+        success: true,
+        data: { todos, total: todos.length, page: 1, limit: 20 },
+      })
 
       await useTodoStore.getState().fetchTodos()
 
@@ -128,7 +131,10 @@ describe('Todo Store', () => {
     })
 
     it('should handle empty array response', async () => {
-      mockJson.mockResolvedValue({ success: true, data: [] })
+      mockJson.mockResolvedValue({
+        success: true,
+        data: { todos: [], total: 0, page: 1, limit: 20 },
+      })
 
       await useTodoStore.getState().fetchTodos()
 
@@ -176,7 +182,10 @@ describe('Todo Store', () => {
       const fetchPromise = useTodoStore.getState().fetchTodos()
       expect(useTodoStore.getState().loading).toBe(true)
 
-      resolvePromise({ json: () => Promise.resolve({ success: true, data: [] }) })
+      resolvePromise({
+        json: () =>
+          Promise.resolve({ success: true, data: { todos: [], total: 0, page: 1, limit: 20 } }),
+      })
       await fetchPromise
 
       expect(useTodoStore.getState().loading).toBe(false)

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

@@ -0,0 +1,36 @@
+/**
+ * @framework-baseline entry-stores-v1
+ *
+ * Entry SSR store 种子（全量版）。
+ * 本文件在模板仓库中为全量实现；CLI 脚手架时会按 preset 重新生成
+ * （src/generators/entry-stores.ts），preset 不含 todo 模块时为空实现，
+ * 避免 entry-server 悬空导入导致构建失败。
+ */
+
+import { useTodoStore } from './todoStore'
+import type { Todo } from '@shared/schemas'
+
+export interface SSRData {
+  todos?: Todo[]
+  [key: string]: unknown
+}
+
+export interface EntryStoreSnapshot {
+  todos: Todo[]
+  loading: boolean
+}
+
+export function snapshotEntryStores(): EntryStoreSnapshot {
+  const state = useTodoStore.getState()
+  return { todos: state.todos, loading: state.loading }
+}
+
+export function seedEntryStores(data: SSRData): void {
+  if (data.todos) {
+    useTodoStore.setState({ todos: data.todos, loading: false })
+  }
+}
+
+export function restoreEntryStores(snapshot: EntryStoreSnapshot): void {
+  useTodoStore.setState({ todos: snapshot.todos, loading: snapshot.loading })
+}

package/template/src/client/stores/notificationStore.ts

@@ -154,20 +154,20 @@ export const useNotificationStore = create<NotificationState>(set => ({
 
       conn.onStatusChange(status => {
         if (import.meta.env.DEV) {
-          console.log('[SSE] Status changed:', status)
+          console.debug('[SSE] Status changed:', status)
         }
         set({ sseConnected: status === 'open' })
       })
 
       conn.on('connected', payload => {
         if (import.meta.env.DEV) {
-          console.log('[SSE] Connected:', payload)
+          console.debug('[SSE] Connected:', payload)
         }
       })
 
       conn.on('notification', notification => {
         if (import.meta.env.DEV) {
-          console.log('[SSE] Received notification:', notification)
+          console.debug('[SSE] Received notification:', notification)
         }
         set(state => {
           if (state.notifications.some(n => n.id === notification.id)) {
@@ -186,7 +186,7 @@ export const useNotificationStore = create<NotificationState>(set => ({
 
       sseClient = conn
       if (import.meta.env.DEV) {
-        console.log('[SSE] Client initialized')
+        console.debug('[SSE] Client initialized')
       }
     } catch (error) {
       console.error('[SSE] Failed to connect:', error)

package/template/src/client/stores/todoStore.ts

@@ -27,10 +27,10 @@ export const useTodoStore = create<TodoState>(set => ({
   fetchTodos: async () => {
     set({ loading: true, error: null })
     try {
-      const response = await apiClient.api.todos.$get()
+      const response = await apiClient.api.todos.$get({ query: {} })
       const result = await response.json()
       if (result.success) {
-        set({ todos: result.data, loading: false })
+        set({ todos: result.data.todos, loading: false })
       } else {
         set({ error: result.error, loading: false })
       }

package/template/src/merchant/pages/DisputesPage.tsx

@@ -15,7 +15,7 @@ export const DisputesPage: FC = () => {
   const fetchDisputes = useCallback(async () => {
     setLoading(true)
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       const response = await apiClient.api.merchant.disputes.$get()
       const result = await response.json()
       if (result.success === true && result.data) {
@@ -35,7 +35,7 @@ export const DisputesPage: FC = () => {
 
   const handleResolve = async (disputeId: string) => {
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       await apiClient.api.merchant.disputes[':id'].resolve.$post({
         param: { id: disputeId },
       })
@@ -47,7 +47,7 @@ export const DisputesPage: FC = () => {
 
   const handleClose = async (disputeId: string) => {
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       await apiClient.api.merchant.disputes[':id'].close.$post({
         param: { id: disputeId },
       })

package/template/src/merchant/pages/OrdersPage.tsx

@@ -16,7 +16,7 @@ export const OrdersPage: FC = () => {
   const fetchOrders = useCallback(async () => {
     setLoading(true)
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       const response = await apiClient.api.merchant.orders.$get()
       const result = await response.json()
       if (result.success === true && result.data) {

package/template/src/merchant/pages/ProductsPage.tsx

@@ -17,7 +17,7 @@ export const ProductsPage: FC = () => {
   const fetchProducts = useCallback(async () => {
     setLoading(true)
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       const response = await apiClient.api.merchant.products.$get()
       const result = await response.json()
       if (result.success === true && result.data) {

package/template/src/merchant/pages/SettingsPage.tsx

@@ -11,7 +11,7 @@ export const SettingsPage: FC = () => {
 
   const handleSave = async (values: unknown) => {
     try {
-      // @ts-expect-error - Hono type depth limit in full template with 15+ modules; resolves in generated projects
+      // @ts-expect-error Hono RPC type depth exceeds TypeScript recursion limit in fullstack-admin preset with 15+ modules
       await apiClient.api.merchant.settings.$put({ json: values })
       message.success('Settings saved successfully')
     } catch {

package/template/src/server/__tests__/integration/isr-full-flow.test.ts

@@ -0,0 +1,251 @@
+/**
+ * ISR Full Flow Integration Test
+ *
+ * Simulates the complete request lifecycle:
+ * 1. First visit → miss → render → cache store → response
+ * 2. Second visit → fresh cache hit → instant response
+ * 3. After maxAge → stale → return cached + background revalidate
+ * 4. After purge → miss → re-render with new data
+ * 5. DB error → graceful fallback to shell
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { createISRCache } from '@server/core/isr-cache'
+import { isrRegistry } from '@server/core/isr-registry'
+import { renderISRPage } from '@server/core/isr-renderer'
+import { purgePage, setISRCache, purgeAllPages } from '@server/core/isr-invalidation'
+
+// We test with a mock module — no real DB needed
+describe('ISR Full Flow Integration', () => {
+  let cache: ReturnType<typeof createISRCache>
+  let fetchCounter: { value: number }
+  let mockData: Array<{ id: number; title: string; status: string }>
+
+  beforeEach(() => {
+    mockData = [
+      { id: 1, title: 'Task 1', status: 'completed' },
+      { id: 2, title: 'Task 2', status: 'pending' },
+    ]
+    fetchCounter = { value: 0 }
+    cache = createISRCache({ maxAge: 1, staleWhileRevalidate: 2 })
+    setISRCache(cache)
+
+    // Register into GLOBAL registry (so purgeAllPages works)
+    isrRegistry.register({
+      module: 'test',
+      match: '/test',
+      fetch: async () => {
+        fetchCounter.value++
+        return { items: mockData }
+      },
+      meta: () => ({ title: 'Test Page', description: 'Test description' }),
+    })
+  })
+
+  afterEach(async () => {
+    await cache.purgePattern('isr:*')
+  })
+
+  /**
+   * Helper: simulate a full ISR request
+   */
+  async function isrRequest(
+    pathname: string,
+    template:
+      | string
+      | null = '<!DOCTYPE html><html><head><title>Old</title></head><body><div id="root"></div></body></html>'
+  ): Promise<{ html: string; status: string; fetched: number }> {
+    const fetchedBefore = fetchCounter.value
+
+    // 1. Check cache
+    const cached = await cache.lookup(pathname)
+
+    if (cached.status === 'fresh' && cached.html) {
+      return { html: cached.html, status: 'fresh', fetched: fetchedBefore }
+    }
+
+    if (cached.status === 'stale' && cached.html) {
+      // Background revalidate (simulated)
+      const entry = isrRegistry.match(pathname)!
+      const data = await entry.fetch(pathname, {})
+      const meta = entry.meta(data, pathname)
+      const html = renderISRPage({ template, meta })
+      await cache.store(pathname, html)
+      return { html: cached.html, status: 'stale', fetched: fetchCounter.value }
+    }
+
+    // Miss: render fresh
+    const entry = isrRegistry.match(pathname)
+    if (!entry) throw new Error(`No handler for ${pathname}`)
+
+    const data = await entry.fetch(pathname, {})
+    const meta = entry.meta(data, pathname)
+    const html = renderISRPage({ template, meta })
+    await cache.store(pathname, html)
+
+    return { html, status: 'miss', fetched: fetchCounter.value }
+  }
+
+  describe('Step 1: First visit (cold cache)', () => {
+    it('should render fresh HTML on first visit', async () => {
+      const result = await isrRequest('/test')
+
+      expect(result.status).toBe('miss')
+      expect(result.fetched).toBe(1)
+      expect(result.html).toContain('<title>Test Page</title>')
+      expect(result.html).toContain('name="generator" content="ISR-SSG"')
+    })
+
+    it('should store result in cache after first visit', async () => {
+      await isrRequest('/test')
+      const cached = await cache.lookup('/test')
+      expect(cached.status).toBe('fresh')
+      expect(cached.html).not.toBeNull()
+    })
+  })
+
+  describe('Step 2: Second visit (warm cache)', () => {
+    it('should serve from cache without re-fetching', async () => {
+      // First visit
+      await isrRequest('/test')
+      expect(fetchCounter.value).toBe(1)
+
+      // Second visit
+      const result = await isrRequest('/test')
+      expect(result.status).toBe('fresh')
+      expect(fetchCounter.value).toBe(1) // No additional fetch
+      expect(result.html).toContain('<title>Test Page</title>')
+    })
+
+    it('should be faster (no fetch call)', async () => {
+      await isrRequest('/test')
+      const fetchedBefore = fetchCounter.value
+
+      await isrRequest('/test')
+      expect(fetchCounter.value).toBe(fetchedBefore) // No new fetch
+    })
+  })
+
+  describe('Step 3: After maxAge (stale)', () => {
+    it('should return stale cache and background revalidate', async () => {
+      // First visit
+      await isrRequest('/test')
+
+      // Wait for cache to become stale (maxAge=1s)
+      await new Promise(r => setTimeout(r, 1200))
+
+      const result = await isrRequest('/test')
+      expect(result.status).toBe('stale')
+      // Should have revalidated in background
+      expect(fetchCounter.value).toBe(2)
+    })
+  })
+
+  describe('Step 4: After purge', () => {
+    it('should re-render after purge with updated data', async () => {
+      // First visit with v1 data
+      await isrRequest('/test')
+      expect(fetchCounter.value).toBe(1)
+
+      // Update data
+      mockData.push({ id: 3, title: 'Task 3', status: 'pending' })
+
+      // Purge
+      await purgePage('/test')
+
+      // Next visit should re-render
+      const result = await isrRequest('/test')
+      expect(result.status).toBe('miss')
+      expect(fetchCounter.value).toBe(2)
+    })
+
+    it('should support purgeAllPages', async () => {
+      await isrRequest('/test')
+
+      await purgeAllPages()
+
+      const cached = await cache.lookup('/test')
+      expect(cached.status).toBe('miss')
+    })
+  })
+
+  describe('Step 5: DB error handling', () => {
+    it('should handle fetch error gracefully', async () => {
+      // Replace fetcher with one that throws
+      isrRegistry.clear()
+      isrRegistry.register({
+        module: 'test',
+        match: '/test',
+        fetch: async () => {
+          throw new Error('DB unavailable')
+        },
+        meta: () => ({ title: 'Test', description: 'desc' }),
+      })
+
+      // The CF entry wraps this in try/catch, but at the module level
+      // the error propagates. The entry catches it and falls back.
+      await expect(isrRequest('/test')).rejects.toThrow('DB unavailable')
+    })
+
+    it('should serve stale cache even if fresh render fails', async () => {
+      // First render succeeds with good data
+      isrRegistry.clear()
+      isrRegistry.register({
+        module: 'test',
+        match: '/test',
+        fetch: async () => ({ items: mockData }),
+        meta: () => ({ title: 'Test', description: 'desc' }),
+      })
+
+      await isrRequest('/test')
+      const cached = await cache.lookup('/test')
+      expect(cached.status).toBe('fresh')
+
+      // Wait for stale
+      await new Promise(r => setTimeout(r, 1200))
+
+      // Even if data changes, stale cache is served
+      const result = await isrRequest('/test')
+      expect(result.status).toBe('stale')
+      expect(result.html).toContain('<title>Test</title>')
+    })
+  })
+
+  describe('Multiple routes', () => {
+    it('should cache routes independently', async () => {
+      isrRegistry.clear()
+      isrRegistry.registerMany([
+        {
+          module: 'a',
+          match: '/a',
+          fetch: async () => ({ items: [{ id: 1, title: 'A1', status: 'pending' }] }),
+          meta: () => ({ title: 'A', description: 'a' }),
+        },
+        {
+          module: 'b',
+          match: '/b',
+          fetch: async () => ({ items: [{ id: 2, title: 'B2', status: 'pending' }] }),
+          meta: () => ({ title: 'B', description: 'b' }),
+        },
+      ])
+
+      const aResult = await isrRequest('/a')
+      const bResult = await isrRequest('/b')
+
+      expect(aResult.html).toContain('<title>A</title>')
+      expect(bResult.html).toContain('<title>B</title>')
+
+      // Purge /a doesn't affect /b
+      await cache.purge('/a')
+      expect((await cache.lookup('/a')).status).toBe('miss')
+      expect((await cache.lookup('/b')).status).toBe('fresh')
+    })
+  })
+
+  describe('Non-ISR routes', () => {
+    it('should not match unregistered routes', () => {
+      expect(isrRegistry.match('/unknown')).toBeNull()
+      expect(isrRegistry.isISRRoute('/unknown')).toBe(false)
+    })
+  })
+})