Molecule.dev

@molecule/app-query-tanstack

Provider bond · query · App (browser) · v1.0.1 · Apache-2.0

TanStack Query bond for @molecule/app-query — the query-core cache behind the molecule contract

npm install @molecule/app-query-tanstack

npm · Source on GitHub · Implements @molecule/app-query

How it works

@molecule/app-query-tanstack is a provider bond on the app (browser) side: it implements the query core interface (@molecule/app-query) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { QueryClient } from '@tanstack/query-core'
import { setProvider } from '@molecule/app-query'
import { createProvider, provider } from '@molecule/app-query-tanstack'

setProvider(provider) // its own client
// or share the app's:
setProvider(createProvider({ client: new QueryClient() }))

Works with: @molecule/app-query

Reference

TanStack Query bond for @molecule/app-query.

The molecule query contract over @tanstack/query-core: the same fetch / prefetch / get / subscribe calls, backed by TanStack's cache, deduplication, staleness and garbage collection. Wrap an app's existing TanStack client so molecule packages and the app's own hooks share one cache.

Quick Start

import { QueryClient } from '@tanstack/query-core'
import { setProvider } from '@molecule/app-query'
import { createProvider, provider } from '@molecule/app-query-tanstack'

setProvider(provider) // its own client
// or share the app's:
setProvider(createProvider({ client: new QueryClient() }))

Type

provider

Installation

npm install @molecule/app-query-tanstack @molecule/app-query @tanstack/query-core

API

Interfaces

TanstackQueryConfig

Provider-specific configuration options.

interface TanstackQueryConfig {
  /**
   * An existing TanStack `QueryClient` to wrap, so an app that already uses
   * TanStack Query (its devtools, its hooks) shares one cache with molecule
   * packages. When omitted, each `createClient()` makes its own.
   */
  client?: TanstackQueryClient
}

Functions

createProvider(config)

Creates a TanStack Query provider.

function createProvider(config?: TanstackQueryConfig): QueryProvider
  • config — Provider configuration.

Returns: A query provider.

Constants

provider

Default TanStack Query provider instance.

const provider: QueryProvider

Core Interface

Implements @molecule/app-query interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-query'
import { provider } from '@molecule/app-query-tanstack'

export function setupQueryTanstack(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/app-query ^1.0.0

Runtime Dependencies

  • @molecule/app-query

  • @tanstack/query-core

  • Retries are off. The contract says a failed fetch rejects and is not cached; TanStack's default of three retries would hide that. Wrap fetch yourself if a query should retry.

  • invalidate(key) marks matching queries stale without refetching them; observers refetch on their next subscription and fetch() refetches on its next call, exactly as with the memory bond.

  • A query nobody observes is garbage-collected gcMs after its last use (TanStack's gcTime), so get() can return undefined for something fetched long ago; treat it as a cache.

  • Framework hooks live in @molecule/app-query-react, not here; this bond depends only on @tanstack/query-core.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • Opening a detail page after hovering its link shows no loading state (the document was warmed) and the page is the right one.
  • Opening the same page twice fetches it once (check the network panel).
  • Going back to a page painted earlier paints at once, from memory.
  • After the app invalidates a key (an edit, a refresh action), the next view shows the new data.
  • With the browser's data-saver on, hovering links fetches nothing.