Copy-paste patterns for real apps

// src/lib/tag-contract.ts
import { defineTags } from "@tanstack-tools/query-tags"

export const appTags = defineTags({
  todos: {
    list:    () => ["todos"],
    summary: () => ["todos", "summary"],
    byId:    (id: string) => ["todo", id],
  },
  dashboard: {
    stats: () => ["dashboard", "stats"],
  },
})

// components/TodoList.tsx — query on /todos route
useQuery({
  queryKey: ["todos", "list"],
  queryFn: fetchTodos,
  meta: { tags: [appTags.todos.list()] },
})

// components/DashboardStats.tsx — query on /dashboard route
useQuery({
  queryKey: ["dashboard", "stats"],
  queryFn: fetchStats,
  meta: { tags: [appTags.dashboard.stats()] },
})

// src/lib/tag-invalidation.server.ts
import { createTagInvalidationSystem } from "@tanstack-tools/query-tags/server"

export const tagInvalidation = createTagInvalidationSystem({
  // Each user gets an isolated SSE channel.
  // Invalidating user A never triggers a refetch for user B.
  resolveScope: (ctx: { userId: string }) => ({
    kind: "user",
    id: ctx.userId,
  }),
})

// Invalidate only for a specific user
await tagInvalidation.invalidateTags({
  tags: [appTags.todos()],
  scope: { kind: "user", id: user.id },
  context: { userId: user.id },
})

// 1. Tag the query as usual
const todosQuery = useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  meta: { tags: [appTags.todos.list()] },
})

// 2. Mutation: update cache optimistically, let server + SSE confirm
const addMutation = useMutation({
  mutationFn: (name: string) => createTodoFn({ data: { name } }),

  onMutate: async (name) => {
    // Prevent the in-flight refetch from overwriting our optimistic value
    await queryClient.cancelQueries({ queryKey: ["todos"] })

    // Snapshot + optimistically set
    const previous = queryClient.getQueryData<Todo[]>(["todos"]) ?? []
    queryClient.setQueryData(["todos"], [{ id: -1, name, status: "pending" }, ...previous])

    return { previous }
  },

  onError: (_err, _name, ctx) => {
    // Roll back on failure
    queryClient.setQueryData(["todos"], ctx?.previous)
  },

  onSettled: () => {
    // The server also calls invalidateTags() — SSE will trigger a fresh
    // refetch regardless of success or failure. This is the safety net.
    queryClient.invalidateQueries({ queryKey: ["todos"] })
  },
})

// Tag hierarchy — parent nodes cascade to all children
export const appTags = defineTags({
  products: {
    list:  () => ["products"],
    byId:  (id: string) => ["product", id],
    stock: (id: string) => ["product", id, "stock"],
    price: (id: string) => ["product", id, "price"],
  },
  cart: {
    items:  () => ["cart", "items"],
    totals: () => ["cart", "totals"],
  },
})

// appTags.products()           → invalidates list + byId(*) + stock(*) + price(*)
// appTags.products.byId("x")   → invalidates only that one product
// appTags.cart()               → invalidates items + totals

// Flash sale: one call fans out across the entire product hierarchy
await tagInvalidation.invalidateTags({
  tags: [
    appTags.products(),    // all product queries
    appTags.cart(),        // cart re-prices itself too
  ],
})

// Price change on a single product: only that product + its cart entry
await tagInvalidation.invalidateTags({
  tags: [
    appTags.products.byId(productId),
    appTags.products.price(productId),
    appTags.cart.totals(),
  ],
})

// src/queries/todos.ts — shared query factories
import { withTags } from "@tanstack-tools/query-tags"

// Define once, use everywhere — no meta object scattered across files
export const todosListQuery = () =>
  withTags(
    { queryKey: ["todos"], queryFn: fetchTodos },
    [appTags.todos.list()],
  )

export const todoByIdQuery = (id: string) =>
  withTags(
    { queryKey: ["todo", id], queryFn: () => fetchTodoById(id) },
    [appTags.todos.byId(id)],
  )

// Usage in components — one import, no boilerplate
import { todosListQuery, todoByIdQuery } from "@/queries/todos"

// In a route loader (data prefetched, Suspense-friendly)
export const Route = createFileRoute("/todos")({
  loader: ({ context }) =>
    context.queryClient.ensureQueryData(todosListQuery()),
})

// In a component (cache already warm from loader)
function TodoList() {
  const { data } = useSuspenseQuery(todosListQuery())
  return <ul>{data.map(t => <li key={t.id}>{t.name}</li>)}</ul>
}

// Single item
function TodoDetail({ id }: { id: string }) {
  const { data } = useSuspenseQuery(todoByIdQuery(id))
  return <article>{data.name}</article>
}