TanStack Query Integration

TanStack Query is an optional advanced integration. Use it when the app needs query keys, cancellation, refetch, and invalidation around SDUI screens or request actions. For small apps, a simple request executor is enough.

Install

pnpm add @sdui-kit/core @sdui-kit/tanstack-query @tanstack/query-core

Install your UI adapter separately, for example @sdui-kit/react or @sdui-kit/vue.

Adapter Shape

Keep TanStack imports in the app or @sdui-kit/tanstack-query, not in core. Request execution can still be a plain function:

const actionRunner = new ActionRunner({
  request: ({ endpoint, method, body, params, signal }) =>
    api.request({ url: endpoint, method, data: body, params, signal }),
})

Move to explicit adapters when you also want cache coordination:

const dataAdapter: DataAdapter = {
  request: ({ endpoint, method, body, params, signal }) =>
    api.request({ url: endpoint, method, data: body, params, signal }),
}

const cacheAdapter: CacheAdapter = {
  get: (key) => queryClient.getQueryData([key]),
  set: (key, value) => queryClient.setQueryData([key], value),
  invalidate: (tags) =>
    queryClient.invalidateQueries({
      predicate: (query) => matchesSDUITag(query.queryKey, tags),
    }),
}

Screen Queries

Build screen query keys from route context:

const screenKey = ['sdui-screen', route.path, route.params, route.query]

const screen = useQuery({
  queryKey: screenKey,
  queryFn: ({ signal }) => fetchScreen({ route, signal }),
})

The query function returns SDUIScreenResponse. Pass the resulting state into ScreenStore or expose it through a TanStack-backed ScreenStore implementation.

Invalidation

Backend can attach cache tags to screens and mutations:

{
  "cache": {
    "tags": [{ "type": "Application", "id": "42" }]
  }
}

After a mutation with invalidate, ActionRunner calls CacheAdapter.invalidate(tags) if a cache adapter exists. The TanStack adapter decides how SDUI tags map to query keys.

Notes

• Pass AbortSignal through query functions.
• Keep query keys deterministic.
• Do not expose TanStack-specific fields in backend payloads.