Feat: Preact Adapter

[theVedanta]

🎯 Changes

Makes a Preact Adapter for Tanstack Query. The main motivations are bundle sizes and ensuring compatibility with the events architecture.

✅ Checklist

• [x] I have followed the steps in the Contributing guide.
• [ ] I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• [ ] This change affects published code, and I have generated a changeset.
• [ ] This change is docs/CI/dev-only (no release).

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: a9c5c75689300e3f4e4838966107a798aac6c080

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai[bot]]

Walkthrough

Adds a new @tanstack/preact-query package and a Preact + Vite example; implements Preact bindings (hooks, providers, hydration, suspense/error-boundary utilities), extensive TypeScript typings and helpers, build/test configuration, and a large suite of runtime and type tests.

Changes

Cohort / File(s)	Summary
Example Preact Application examples/preact/simple/.gitignore, examples/preact/simple/README.md, examples/preact/simple/index.html, examples/preact/simple/package.json, examples/preact/simple/src/index.tsx, examples/preact/simple/src/style.css, examples/preact/simple/tsconfig.json, examples/preact/simple/vite.config.ts	Adds a minimal Preact + Vite example project (README, entry HTML, TSX app, styles, TS/Vite configs, package.json, .gitignore).
Package config & tooling packages/preact-query/package.json, packages/preact-query/CHANGELOG.md, packages/preact-query/README.md, packages/preact-query/eslint.config.js, packages/preact-query/root.eslint.config.js, packages/preact-query/root.tsup.config.js, packages/preact-query/tsup.config.ts, packages/preact-query/vite.config.ts, packages/preact-query/tsconfig.json, packages/preact-query/tsconfig.legacy.json, packages/preact-query/tsconfig.prod.json, packages/preact-query/test-setup.ts	Introduces package metadata, changelog, README, ESLint, tsup, Vite, and multiple tsconfig variants plus test setup for the new package.
Public API barrel packages/preact-query/src/index.ts	Adds package entrypoint re-exporting hooks, types, providers, and utilities to form the public API surface.
Providers & contexts packages/preact-query/src/QueryClientProvider.tsx, packages/preact-query/src/IsRestoringProvider.ts, packages/preact-query/src/QueryErrorResetBoundary.tsx, packages/preact-query/src/HydrationBoundary.tsx	Adds QueryClientProvider, IsRestoringProvider, QueryErrorResetBoundary, HydrationBoundary and their exported types/hooks.
Base query orchestration packages/preact-query/src/useBaseQuery.ts	Implements useBaseQuery coordinating observer lifecycle, suspense/error handling, subscriptions, and optional prefetch-in-render behavior.
Query hooks packages/preact-query/src/useQuery.ts, packages/preact-query/src/useInfiniteQuery.ts, packages/preact-query/src/useQueries.ts, packages/preact-query/src/useSuspenseQuery.ts, packages/preact-query/src/useSuspenseInfiniteQuery.ts, packages/preact-query/src/useSuspenseQueries.ts	Adds typed query hooks (useQuery, useInfiniteQuery, useQueries and suspense variants) with overloads and runtime wiring to useBaseQuery/useQueries.
Prefetch & mutation APIs packages/preact-query/src/usePrefetchQuery.tsx, packages/preact-query/src/usePrefetchInfiniteQuery.tsx, packages/preact-query/src/useMutation.ts, packages/preact-query/src/useMutationState.ts, packages/preact-query/src/useIsFetching.ts	Implements prefetch hooks, useMutation, mutation state utilities (useMutationState, useIsMutating) and useIsFetching.
Options & type system packages/preact-query/src/types.ts, packages/preact-query/src/queryOptions.ts, packages/preact-query/src/infiniteQueryOptions.ts, packages/preact-query/src/mutationOptions.ts	Adds comprehensive TypeScript types for options/results and identity helpers (queryOptions, infiniteQueryOptions, mutationOptions) with multiple overloads.
Error & suspense utilities packages/preact-query/src/errorBoundaryUtils.ts, packages/preact-query/src/suspense.ts	Implements helpers for error-boundary retry prevention, suspense timer enforcement, fetch predicates, and optimistic fetch wrapper.
Tests & test utils packages/preact-query/src/__tests__/*, packages/preact-query/src/__tests__/utils.tsx	Adds extensive runtime and TypeScript tests (hydration, SSR, suspense, queries, mutations, persisters, types) plus testing utilities and test setup.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Areas to focus review on:

• useBaseQuery.ts — observer lifecycle, subscription handling, suspense and error throw paths, and experimental prefetch-in-render.
• useQueries.ts & useSuspenseQueries.ts — deep TypeScript inference, overloads, and runtime combine/observer logic.
• HydrationBoundary.tsx — hydration queueing, immediate vs deferred hydration decisions, and state comparison logic.
• types.ts / queryOptions.ts / infiniteQueryOptions.ts / mutationOptions.ts — complex generics, overloads, SkipToken handling, and exported type shapes.
• errorBoundaryUtils.ts and suspense.ts — correctness of retry prevention and suspense timer/clamping logic.
• Large test suite — timing assumptions, fake timers, and test utilities alignment with runtime behavior.

Possibly related PRs

• TanStack/query#9605 — related to HydrationBoundary behavior and tests for malformed/missing hydration state.
• TanStack/query#9668 — related to queryOptions / infiniteQueryOptions typing and DataTag/queryKey usage.
• TanStack/query#9634 — touches infiniteQueryOptions and useInfiniteQuery typing/overloads.

Suggested reviewers

• TkDodo
• manudeli

"🐰
I hopped through types and hooks all day,
Bound hydration queues and chased errors away.
Suspense and cache now twine and play—
Preact sings brighter, so carrots, hooray! 🥕"

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description identifies the motivation (bundle size, events architecture compatibility) but is incomplete: the 'tested locally with pnpm run test:pr' checkbox is unchecked, and critically, no changeset was generated despite 'affects published code' being unchecked when a new public package (@tanstack/preact-query) is being added.	Generate a changeset documenting the new @tanstack/preact-query package and its release impact. Mark the 'tested locally' checkbox after confirming tests pass. Consider clarifying which specific bundle size improvements were achieved.
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.10% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Feat: Preact Adapter' clearly and concisely summarizes the main change—adding Preact adapter support to TanStack Query. It is specific, directly related to the changeset, and follows conventional commit format.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 78cf64ad2e5b709f321896b82d1b17e836b1fe38 and a9c5c75689300e3f4e4838966107a798aac6c080.

📒 Files selected for processing (2)

• packages/preact-query/src/__tests__/ssr-hydration.test.tsx (1 hunks)
• packages/preact-query/src/__tests__/useMutation.test.tsx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/preact-query/src/tests/useMutation.test.tsx
• packages/preact-query/src/tests/ssr-hydration.test.tsx

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[alextompkins]

Just wanted to note my appreciation for this, as a member of a team using Tanstack Query with preact 🫶

[theVedanta]

Just wanted to note my appreciation for this, as a member of a team using Tanstack Query with preact 🫶

thank you 😭❤️ feel free to let me know any thoughts you might have on reducing bundle size :)