fix(start-static-server-functions): fall back to the server function on a cache miss

.changeset/static-server-fn-cache-miss-fallback.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-static-server-functions': patch
+---
+
+Fix `staticFunctionMiddleware` failing with `Unexpected token '<', "<!DOCTYPE "... is not valid JSON` when no prerendered cache file exists for a call. The client now treats an unreadable or non-JSON cache response as a miss and invokes the server function instead, and a cache hit is reused from the client cache rather than refetched.

docs/start/framework/react/guide/static-server-functions.md

@@ -33,3 +33,4 @@ This pattern goes as follows:
   - Initially, the prerendered page's html is served and the server function data is embedded in the html
   - When the client mounts, the embedded server function data is hydrated
   - For future client-side invocations, the server function is replaced with a fetch call to the static JSON file
+  - If no cached file exists for that key, the call falls back to invoking the server function normally. This happens when prerendering is disabled, or when the call is made from a route that the prerender pass never reached, so a static server function stays usable instead of failing

packages/start-static-server-functions/package.json

@@ -26,7 +26,7 @@
   "scripts": {
     "clean": "rimraf ./dist && rimraf ./coverage",
     "test": "pnpm test:eslint && pnpm test:types && pnpm test:build && pnpm test:unit",
-    "test:unit": "exit 0; vitest",
+    "test:unit": "vitest",
     "test:unit:dev": "vitest --watch",
     "test:eslint": "eslint ./src",
     "test:types": "pnpm run \"/^test:types:ts[0-9]{2}$/\"",

packages/start-static-server-functions/src/staticFunctionMiddleware.ts

@@ -104,6 +104,17 @@ async function addItemToCache({
   }
 }
 
+/**
+ * Look up a prerendered result for this call.
+ *
+ * Returns `undefined` for a cache miss so the caller can fall back to invoking
+ * the server function. A miss is the normal case whenever the cache file was
+ * never written, for example when `prerender` is disabled or when the route
+ * that makes this call is not reached during the prerender pass. The request
+ * for the missing file is then answered by the application's catch-all route,
+ * which serves the HTML shell, so neither the status code nor the body can be
+ * trusted without checking.
+ */
 const fetchItem = async ({
   data,
   functionId,
@@ -114,13 +125,42 @@ const fetchItem = async ({
   const hash = jsonToFilenameSafeString(data)
   const url = await getStaticCacheUrl({ functionId, hash })
 
-  let result: any = staticClientCache?.get(url)
+  const cached = staticClientCache?.get(url)
+  if (cached !== undefined) {
+    return cached
+  }
 
-  result = await fetch(url, {
-    method: 'GET',
-  })
-    .then((r) => r.json())
-    .then((d) => fromJSON(d, { plugins: getDefaultSerovalPlugins() }))
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method: 'GET',
+    })
+  } catch {
+    // The cache file could not be requested at all.
+    return undefined
+  }
+
+  if (!response.ok) {
+    return undefined
+  }
+
+  // The HTML shell is served with a 200 in some setups, so the content type is
+  // what actually distinguishes a cache hit from the fallback document.
+  if (!response.headers.get('content-type')?.includes('application/json')) {
+    return undefined
+  }
+
+  let result: any
+  try {
+    result = fromJSON(await response.json(), {
+      plugins: getDefaultSerovalPlugins(),
+    })
+  } catch {
+    // The file exists but is not a payload this build can read.
+    return undefined
+  }
+
+  staticClientCache?.set(url, result)
 
   return result
 }

packages/start-static-server-functions/tests/staticFunctionMiddleware.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { toJSONAsync } from 'seroval'
+
+// `getDefaultSerovalPlugins` reads the Start options through an isomorphic
+// function. Uncompiled, that chain resolves to its server implementation and
+// wants a Start context in AsyncLocalStorage, which a browser never has. The
+// adapter list is irrelevant to the cache lookup under test, so stub it out and
+// serialize the fixtures the same way.
+vi.mock('@tanstack/start-client-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@tanstack/start-client-core')>()
+  return { ...actual, getDefaultSerovalPlugins: () => [] }
+})
+
+const { staticFunctionMiddleware } =
+  await import('../src/staticFunctionMiddleware')
+
+const clientMiddleware = staticFunctionMiddleware.options.client!
+
+/** The result the live server function produces when the cache is not used. */
+const LIVE_RESULT = { result: 'from the server function' }
+
+/**
+ * Each test uses its own `data`, so it hashes to its own cache URL and cannot
+ * be served by the module level client cache another test populated.
+ */
+function callClientMiddleware(data: unknown) {
+  const next = vi.fn(async () => LIVE_RESULT)
+  const promise = clientMiddleware({
+    serverFnMeta: { id: 'test_fn' },
+    data,
+    context: {},
+    next,
+  } as any)
+  return { promise, next }
+}
+
+function jsonResponse(body: string, status = 200) {
+  return new Response(body, {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+/** What the application's catch-all route serves for a missing cache file. */
+function htmlShellResponse(status = 200) {
+  return new Response('<!DOCTYPE html><html><body></body></html>', {
+    status,
+    headers: { 'content-type': 'text/html' },
+  })
+}
+
+beforeEach(() => {
+  vi.stubEnv('NODE_ENV', 'production')
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('staticFunctionMiddleware client on a cache miss', () => {
+  test('falls back to the server function when the HTML shell is served with a 200', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => htmlShellResponse(200)),
+    )
+
+    const { promise, next } = callClientMiddleware({ case: 'html-200' })
+
+    await expect(promise).resolves.toBe(LIVE_RESULT)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  test('falls back to the server function on a 404', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => htmlShellResponse(404)),
+    )
+
+    const { promise, next } = callClientMiddleware({ case: 'html-404' })
+
+    await expect(promise).resolves.toBe(LIVE_RESULT)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  test('falls back to the server function when the body is not valid JSON', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => jsonResponse('not json at all')),
+    )
+
+    const { promise, next } = callClientMiddleware({ case: 'bad-json' })
+
+    await expect(promise).resolves.toBe(LIVE_RESULT)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  test('falls back to the server function when the request fails outright', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw new TypeError('Failed to fetch')
+      }),
+    )
+
+    const { promise, next } = callClientMiddleware({ case: 'network-error' })
+
+    await expect(promise).resolves.toBe(LIVE_RESULT)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('staticFunctionMiddleware client on a cache hit', () => {
+  test('returns the prerendered result without calling the server function', async () => {
+    const payload = JSON.stringify(
+      await toJSONAsync({
+        result: 'from the static cache',
+        context: { user: 'sean' },
+      }),
+    )
+    const fetchMock = vi.fn(async () => jsonResponse(payload))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const first = callClientMiddleware({ case: 'hit' })
+    await expect(first.promise).resolves.toMatchObject({
+      result: 'from the static cache',
+      context: { user: 'sean' },
+    })
+    expect(first.next).not.toHaveBeenCalled()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+
+    // The same call is served from the client cache rather than refetched.
+    const second = callClientMiddleware({ case: 'hit' })
+    await expect(second.promise).resolves.toMatchObject({
+      result: 'from the static cache',
+    })
+    expect(second.next).not.toHaveBeenCalled()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('staticFunctionMiddleware client outside production', () => {
+  test('does not request the cache at all', async () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    const fetchMock = vi.fn(async () => jsonResponse('{}'))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { promise, next } = callClientMiddleware({ case: 'development' })
+
+    await expect(promise).resolves.toBe(LIVE_RESULT)
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})