Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Projects and Practice

Project: Issue Tracker

Build a small issue tracker with TanStack Query: query keys for lists and details, filters, a create mutation, targeted invalidation and cache seeding.

In this first project you combine what the earlier chapters taught into one small app: an issue tracker with a filterable list, a detail panel, a form to create issues and a button to close them. There is no real backend, so a fake in-memory API with delays stands in for the server. Everything else is the real TanStack Query code you would write in production.

By the end you will have used query keys with filters, dependent detail queries, useMutation, invalidateQueries with partial keys, setQueryData to seed the detail cache, and placeholderData to avoid flicker. Read the code, run it, then do the exercises at the end.

Plan the cache first

Before writing components, decide your keys. A key hierarchy makes invalidation precise.

JavaScript
const issueKeys = {
  all: ["issues"],
  lists: () => [...issueKeys.all, "list"],
  list: (status) => [...issueKeys.lists(), { status }],
  details: () => [...issueKeys.all, "detail"],
  detail: (id) => [...issueKeys.details(), id],
};

With this layout, invalidateQueries({ queryKey: issueKeys.lists() }) refreshes every list (open, closed, all) without touching details, and issueKeys.all refreshes everything. A key factory also stops typos: the string "issues" appears in exactly one place.

flowchart TD
  A["['issues']"] --> B["['issues','list']"]
  A --> C["['issues','detail']"]
  B --> D["list: status open"]
  B --> E["list: status closed"]
  C --> F["detail 1"]
  C --> G["detail 2"]

Invalidating a node refreshes every query beneath it.

The app

Issue tracker

Try this sequence: switch between open and closed (the old list stays dimmed while the new one loads, thanks to keepPreviousData), open an issue, close it, and go back to the open tab. The closed issue is gone because invalidateQueries on the list prefix refreshed it.

What each decision buys you

  • Key factory. One definition of every key, with a hierarchy you can invalidate at any level.
  • placeholderData: keepPreviousData. Changing the filter changes the key, which would normally show a spinner. Keeping the previous data avoids a layout jump (see Paginated Queries).
  • enabled: id != null. The detail query stays idle until something is selected.
  • setQueryData in onSuccess. The server already returned the full issue, so there is no reason to fetch it again when the user clicks it. The detail panel opens instantly.
  • Invalidate lists, not details. The detail was just written with fresh data, so only the lists need a refetch. Invalidating issueKeys.all would work but would refetch a detail you already have.

Extending the project

These steps are also a good test of your understanding:

  1. Optimistic close. Use the pattern from Optimistic Updates in the Cache so the issue closes instantly and rolls back if the fake server throws.
  2. Prefetch on hover. Call queryClient.prefetchQuery({ queryKey: issueKeys.detail(i.id), queryFn: ... }) in onMouseEnter, with a staleTime, so the detail is usually ready before the click (Prefetching and Initial Data).
  3. Error simulation. Make api.get fail for one id and show a retry button that calls refetch().
  4. Tests. Write tests for useCreateIssue with a fresh QueryClient per test (Testing Queries and Mutations).

Common mistakes in this project

  • Writing the same key by hand in three files, then missing one when the shape changes.
  • Putting the filter in the key but forgetting to pass it to the queryFn, so every tab shows the same data.
  • Doing the cache update in the component's mutate(vars, { onSuccess }) instead of the hook's onSuccess: per-call callbacks do not run if the component unmounts, but the hook's do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which call refreshes the open, closed and all lists but not individual issue details?

    Partial key matching refreshes every query whose key starts with ['issues', 'list'], which covers all filtered lists and no details.
  2. 2. Why does the project call setQueryData with the issue returned by the create mutation?

    The server response is the full issue, so writing it under the detail key makes the detail panel instant with no extra request.
  3. 3. What does placeholderData: keepPreviousData do when the status filter changes?

    The key changes, so the new query has no data yet. keepPreviousData lends the old result until the new one arrives, and isPlaceholderData is true meanwhile.
  4. 4. Why is a key factory useful?

    A factory avoids typos and makes the hierarchy explicit, which is what partial-key invalidation relies on.

Summary

  • Design the key hierarchy first; a factory keeps it consistent.
  • Lists and details are separate queries; invalidate lists after changes and seed details with setQueryData.
  • keepPreviousData makes filter changes smooth; enabled keeps dependent queries idle.
  • Put cache updates in the hook's onSuccess, so they run even if the component unmounts.
  • Extend the app with optimistic updates, hover prefetching and tests.

Next: Project: Infinite Photo Feed