From 479a8dbf3caa82cbca78e32a04cb969f8caaeede Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 27 Oct 2026 00:41:37 +0900 Subject: [PATCH] docs(examples/preact/ssr): add ssr example with prefetching, dependent queries and error handling (#12407) * docs(examples/preact/ssr): add ssr example * docs(examples/preact/ssr): prefetch a dependent query and treat the posts as critical content --- docs/config.json | 4 + examples/preact/ssr/.gitignore | 27 ++ examples/preact/ssr/README.md | 6 + examples/preact/ssr/eslint.config.js | 20 ++ examples/preact/ssr/index.html | 19 ++ examples/preact/ssr/package.json | 34 +++ examples/preact/ssr/public/emblem-light.svg | 13 + examples/preact/ssr/server.js | 66 +++++ examples/preact/ssr/src/App.tsx | 53 ++++ examples/preact/ssr/src/entry-client.tsx | 31 ++ examples/preact/ssr/src/entry-server.tsx | 46 +++ examples/preact/ssr/src/makeQueryClient.ts | 13 + .../preact/ssr/src/services/comments/api.ts | 11 + .../ssr/src/services/comments/queries.ts | 11 + .../preact/ssr/src/services/comments/types.ts | 6 + examples/preact/ssr/src/services/posts/api.ts | 9 + .../preact/ssr/src/services/posts/queries.ts | 11 + .../preact/ssr/src/services/posts/types.ts | 6 + examples/preact/ssr/src/services/users/api.ts | 11 + .../preact/ssr/src/services/users/queries.ts | 11 + .../preact/ssr/src/services/users/types.ts | 4 + examples/preact/ssr/tsconfig.json | 21 ++ examples/preact/ssr/vite.config.ts | 9 + pnpm-lock.yaml | 275 ++++++++++++++++++ 24 files changed, 717 insertions(+) create mode 100644 examples/preact/ssr/.gitignore create mode 100644 examples/preact/ssr/README.md create mode 100644 examples/preact/ssr/eslint.config.js create mode 100644 examples/preact/ssr/index.html create mode 100644 examples/preact/ssr/package.json create mode 100644 examples/preact/ssr/public/emblem-light.svg create mode 100644 examples/preact/ssr/server.js create mode 100644 examples/preact/ssr/src/App.tsx create mode 100644 examples/preact/ssr/src/entry-client.tsx create mode 100644 examples/preact/ssr/src/entry-server.tsx create mode 100644 examples/preact/ssr/src/makeQueryClient.ts create mode 100644 examples/preact/ssr/src/services/comments/api.ts create mode 100644 examples/preact/ssr/src/services/comments/queries.ts create mode 100644 examples/preact/ssr/src/services/comments/types.ts create mode 100644 examples/preact/ssr/src/services/posts/api.ts create mode 100644 examples/preact/ssr/src/services/posts/queries.ts create mode 100644 examples/preact/ssr/src/services/posts/types.ts create mode 100644 examples/preact/ssr/src/services/users/api.ts create mode 100644 examples/preact/ssr/src/services/users/queries.ts create mode 100644 examples/preact/ssr/src/services/users/types.ts create mode 100644 examples/preact/ssr/tsconfig.json create mode 100644 examples/preact/ssr/vite.config.ts diff --git a/docs/config.json b/docs/config.json index 446b3a3499..3c6b9f9b1e 100644 --- a/docs/config.json +++ b/docs/config.json @@ -7046,6 +7046,10 @@ { "label": "Prefetching", "to": "framework/preact/examples/prefetching" + }, + { + "label": "SSR", + "to": "framework/preact/examples/ssr" } ] } diff --git a/examples/preact/ssr/.gitignore b/examples/preact/ssr/.gitignore new file mode 100644 index 0000000000..4673b022e5 --- /dev/null +++ b/examples/preact/ssr/.gitignore @@ -0,0 +1,27 @@ +# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. + +# dependencies +/node_modules +/.pnp +.pnp.js + +# testing +/coverage + +# production +/build + +pnpm-lock.yaml +yarn.lock +package-lock.json + +# misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/examples/preact/ssr/README.md b/examples/preact/ssr/README.md new file mode 100644 index 0000000000..1cf8892652 --- /dev/null +++ b/examples/preact/ssr/README.md @@ -0,0 +1,6 @@ +# Example + +To run this example: + +- `npm install` +- `npm run dev` diff --git a/examples/preact/ssr/eslint.config.js b/examples/preact/ssr/eslint.config.js new file mode 100644 index 0000000000..b39d2be6c9 --- /dev/null +++ b/examples/preact/ssr/eslint.config.js @@ -0,0 +1,20 @@ +// @ts-check + +import { tanstackConfig } from '@tanstack/eslint-config' +import pluginQuery from '@tanstack/eslint-plugin-query' +// @ts-ignore: no types for eslint-config-preact +import preact from 'eslint-config-preact' +import { defineConfig } from 'eslint/config' + +export default defineConfig([ + ...preact, + ...tanstackConfig, + ...pluginQuery.configs['flat/recommended-strict'], + { + rules: { + 'no-duplicate-imports': 'off', + 'no-redeclare': 'off', + 'no-unused-vars': 'off', + }, + }, +]) diff --git a/examples/preact/ssr/index.html b/examples/preact/ssr/index.html new file mode 100644 index 0000000000..5cea48a028 --- /dev/null +++ b/examples/preact/ssr/index.html @@ -0,0 +1,19 @@ + + + + + + + + + TanStack Query Preact SSR Example App + + + +
+ + + + diff --git a/examples/preact/ssr/package.json b/examples/preact/ssr/package.json new file mode 100644 index 0000000000..dccbf23d07 --- /dev/null +++ b/examples/preact/ssr/package.json @@ -0,0 +1,34 @@ +{ + "name": "@tanstack/query-example-preact-ssr", + "private": true, + "type": "module", + "scripts": { + "dev": "node server.js", + "build": "vite build --outDir dist/client && vite build --ssr src/entry-server.tsx --outDir dist/server", + "preview": "cross-env NODE_ENV=production node server.js", + "test:eslint": "eslint ./src ./server.js", + "test:types": "tsc --noEmit" + }, + "dependencies": { + "@tanstack/preact-query": "^5.105.0", + "@tanstack/preact-query-devtools": "^5.105.0", + "compression": "^1.8.1", + "devalue": "^6.0.3", + "express": "^5.3.0", + "preact": "^11.0.1", + "preact-render-to-string": "^6.8.0", + "sirv": "^3.0.2" + }, + "devDependencies": { + "@preact/preset-vite": "^2.10.6", + "@tanstack/eslint-plugin-query": "^5.105.0", + "@types/compression": "^1.8.1", + "@types/express": "^5.0.6", + "@types/node": "^24.19.2", + "cross-env": "^10.1.0", + "eslint": "^9.36.0", + "eslint-config-preact": "^2.0.0", + "typescript": "^5.9.3", + "vite": "^8.3.1" + } +} diff --git a/examples/preact/ssr/public/emblem-light.svg b/examples/preact/ssr/public/emblem-light.svg new file mode 100644 index 0000000000..a58e69ad5e --- /dev/null +++ b/examples/preact/ssr/public/emblem-light.svg @@ -0,0 +1,13 @@ + + + + emblem-light + Created with Sketch. + + + + + + + + \ No newline at end of file diff --git a/examples/preact/ssr/server.js b/examples/preact/ssr/server.js new file mode 100644 index 0000000000..99e14c97f8 --- /dev/null +++ b/examples/preact/ssr/server.js @@ -0,0 +1,66 @@ +import fs from 'node:fs/promises' +import express from 'express' + +const isProduction = process.env.NODE_ENV === 'production' +const port = process.env.PORT || 5173 +const base = process.env.BASE || '/' +const serverEntry = './dist/server/entry-server.js' + +const templateHtml = isProduction + ? await fs.readFile('./dist/client/index.html', 'utf-8') + : '' + +const app = express() + +/** @type {import('vite').ViteDevServer | undefined} */ +let vite +if (!isProduction) { + const { createServer } = await import('vite') + vite = await createServer({ + server: { middlewareMode: true }, + appType: 'custom', + base, + }) + app.use(vite.middlewares) +} else { + const compression = (await import('compression')).default + const sirv = (await import('sirv')).default + app.use(compression()) + app.use(base, sirv('./dist/client', { extensions: [] })) +} + +app.use('*all', async (req, res) => { + try { + const url = req.originalUrl.replace(base, '') + + /** @type {string} */ + let template + /** @type {typeof import('./src/entry-server').render} */ + let render + if (vite) { + template = await fs.readFile('./index.html', 'utf-8') + template = await vite.transformIndexHtml(url, template) + render = (await vite.ssrLoadModule('/src/entry-server.tsx')).render + } else { + template = templateHtml + render = (await import(serverEntry)).render + } + + const rendered = await render() + + const html = template + .replace(``, rendered.html) + .replace(``, rendered.state) + + res.status(200).set({ 'Content-Type': 'text/html' }).send(html) + } catch (error) { + const e = /** @type {Error} */ (error) + vite?.ssrFixStacktrace(e) + console.log(e.stack) + res.status(500).end(e.stack) + } +}) + +app.listen(port, () => { + console.log(`Server started at http://localhost:${port}`) +}) diff --git a/examples/preact/ssr/src/App.tsx b/examples/preact/ssr/src/App.tsx new file mode 100644 index 0000000000..47f71c2ae9 --- /dev/null +++ b/examples/preact/ssr/src/App.tsx @@ -0,0 +1,53 @@ +import { useQuery } from '@tanstack/preact-query' +import { commentsQueries } from './services/comments/queries' +import { postsQueries } from './services/posts/queries' +import { usersQueries } from './services/users/queries' + +export default function App() { + // This query was prefetched on the server, so its data is already in the + // server-rendered markup and is available immediately on the client + const postsQuery = useQuery(postsQueries.list()) + + // This query depends on the posts, and was prefetched on the server as well + const authorQuery = useQuery( + usersQueries.detail(postsQuery.data?.[0]?.userId), + ) + + // This query was not prefetched on the server and will not start + // fetching until on the client, both patterns are fine to mix + const commentsQuery = useQuery(commentsQueries.list()) + + return ( +
+

Server Rendering with Preact Query

+

Comments

+

+ {commentsQuery.isPending + ? 'Loading comments on the client...' + : commentsQuery.isError + ? `Error: ${commentsQuery.error.message}` + : `${commentsQuery.data.length} comments`} +

+

Author of the first post

+

+ {authorQuery.isPending + ? 'Loading author...' + : authorQuery.isError + ? `Error: ${authorQuery.error.message}` + : authorQuery.data.name} +

+

Posts

+ {postsQuery.isPending ? ( + 'Loading posts...' + ) : postsQuery.isError ? ( + Error: {postsQuery.error.message} + ) : ( + + )} +
+ ) +} diff --git a/examples/preact/ssr/src/entry-client.tsx b/examples/preact/ssr/src/entry-client.tsx new file mode 100644 index 0000000000..2ad68606ed --- /dev/null +++ b/examples/preact/ssr/src/entry-client.tsx @@ -0,0 +1,31 @@ +import { hydrate } from 'preact' +import { useState } from 'preact/hooks' +import { HydrationBoundary, QueryClientProvider } from '@tanstack/preact-query' +import { PreactQueryDevtools } from '@tanstack/preact-query-devtools' +import App from './App' +import { makeQueryClient } from './makeQueryClient' +import type { DehydratedState } from '@tanstack/preact-query' + +declare global { + interface Window { + __DEHYDRATED_STATE__: DehydratedState + } +} + +function Root({ dehydratedState }: { dehydratedState: DehydratedState }) { + const [queryClient] = useState(() => makeQueryClient()) + + return ( + + + + + + + ) +} + +const rootElement = document.getElementById('root') +if (!rootElement) throw new Error('Missing #root element') + +hydrate(, rootElement) diff --git a/examples/preact/ssr/src/entry-server.tsx b/examples/preact/ssr/src/entry-server.tsx new file mode 100644 index 0000000000..80583e1407 --- /dev/null +++ b/examples/preact/ssr/src/entry-server.tsx @@ -0,0 +1,46 @@ +import { renderToString } from 'preact-render-to-string' +import { uneval } from 'devalue' +import { + QueryClientProvider, + dehydrate, + hydrate, + noop, +} from '@tanstack/preact-query' +import { PreactQueryDevtools } from '@tanstack/preact-query-devtools' +import App from './App' +import { makeQueryClient } from './makeQueryClient' +import { postsQueries } from './services/posts/queries' +import { usersQueries } from './services/users/queries' + +export async function render() { + // The prefetching client: only used to fetch and dehydrate + const prefetchClient = makeQueryClient() + + // The posts are critical content: without `.catch(noop)`, a failed fetch + // throws here and the server responds with an error status + const posts = await prefetchClient.query(postsQueries.list()) + + // The author depends on the first post, so prefetch it once its id is known. + // It's not critical: on failure it's left out of the dehydrated state and + // fetched again on the client + const authorId = posts[0]?.userId + if (authorId) { + await prefetchClient.query(usersQueries.detail(authorId)).catch(noop) + } + + const dehydratedState = dehydrate(prefetchClient) + + // The render client: hydrated with the same state, used for renderToString + const renderClient = makeQueryClient() + hydrate(renderClient, dehydratedState) + + const html = renderToString( + + + + , + ) + + // `uneval` escapes the state so it can't break out of the