Reuse Resource Data Across Routes with TanStack Query

Project records are resource data: they remain owned outside React even while the application holds an in-memory cached copy. In this tutorial, their source will be read-only JSON served locally by Vite; another application might read the same kind of data from an API.

A query cache handles reuse of resource data and preserves the outcome of reads. That responsibility differs from temporary interaction state, such as whether one route’s help panel is open. Do not copy fetched project records into component state or general context merely to share them between routes.

In your own Vite project, install TanStack Query. Then create one QueryClient at module scope in src/main.tsx. This gives the running application one stable cache instead of replacing it during rendering.

Use the default client configuration for now. Later steps add demonstration settings for freshness, retention, and retry behavior.

Run this from the project folder.

Create or replace src/main.tsx. The provider encloses the router and every routed view. Keep any route-level error boundary below this provider so route recovery does not replace the application cache.

Keep route composition below the provider. This navigation shell intentionally has no resource reads yet: later steps replace these temporary route views with query-driven presentations. It uses the three project URLs that the completed application will support.

Create src/App.tsx. This default export matches the import in src/main.tsx.

Create these three files under src/features/projects/, splitting the snippet at each file comment.

Create these read-only fixtures in your Vite project. Files inside public are served from the site root, so the browser requests /data/projects.json—never /public/data/projects.json.

Create the public/data/projects folder before adding the two detail files.

Keep transport and runtime validation in src/features/projects/projectData.ts. A successful HTTP response only gives decoded unknown data; it does not prove that the data is a Project.

Start the file with the shared record contract and validators below. The validators are the boundary that prevents invalid JSON values from entering the typed application.

Begin src/features/projects/projectData.ts with these declarations and validation helpers.

Append these functions to the same projectData.ts file. fetch receives the supplied signal, unsuccessful HTTP responses reject, and response.json() is retained as unknown until validation succeeds.

fetchProjects('archived', signal) currently resolves to []: both fixture records are active. That empty array is valid successful data.

By contrast, a non-OK response, malformed JSON, an invalid record shape, or a detail record whose id differs from the requested ID must reject. Do not replace any of those failures with [] or an invented Project.

A query key is the identity of a result inside one QueryClient. The request URL describes where data is read from, but it does not by itself separate cached results.

For example, the active-project list and archived-project list read the same /data/projects.json resource. They are different results because the normalized status changes which records fetchProjects returns. Their query keys must therefore differ.

Treat every input that changes a returned result as part of that result’s query key.

Keep key shapes in one factory. This prevents one consumer from writing a list key differently from another consumer.

The list key includes normalized status. The detail key includes the project identifier. The detail signature accepts string | null so the key contract is ready for route input; execution guarding comes in the next step.

In src/features/projects/projectQueries.ts, define the shared result identities.

Add the list Hook beneath the factory. useQuery receives the key and a query function. When the URL-derived filter changes, status changes in both places: a new key selects the appropriate cache entry, and the query function reads the matching result.

The query-function context supplies an AbortSignal. Forward it to the data-access function, which forwards it to fetch. That lets TanStack Query cancel an obsolete read rather than leaving transport cancellation disconnected from query management.

Add this to src/features/projects/projectQueries.ts.

A route parameter is input, not proof that a resource can be read. Normalize it before calling the detail Hook: an identifier that does not match the accepted format becomes null.

• A malformed URL such as /projects/not-an-id becomes null. It must not start a request.
• A format-valid URL such as /projects/p-999 can start a request, but its JSON resource may be unavailable. That is a read failure, not an invalid link.
• A valid, available identifier can read and display its project.

This distinction lets the interface report Invalid project link immediately while valid resource reads remain the query cache's responsibility.

Create the route-input helpers in src/features/projects/projectRoute.ts. isProjectId is exported for code that needs a boolean type guard; normalizeProjectId is the route-facing helper used by both detail pages. Unsupported or absent list-filter values normalize to 'all'.

Replace the full contents of src/features/projects/projectQueries.ts with this consolidated version. Step 3 already added useQuery; replacing the file avoids a duplicate import while preserving the list Hook and adding the guarded detail Hook.

Call useProject unconditionally. enabled prevents automatic execution for null, while the query-function guard protects fetchProject if code explicitly invokes a disabled query.

For a detail page, render Invalid project link first when normalization returned null. This branch deliberately does not inspect query flags or offer a refetch action.

For valid input, use query.isLoading for the active initial read. If no data is available after that, render initial-failure feedback. A format-valid but unavailable ID belongs in this failure branch, not in the malformed-link branch.

For a list, availability and emptiness are separate checks. An empty array is successful data, so test its length only after confirming query.data !== undefined.

This complete list view imports the helpers created in this step. The archived filter currently produces a successful empty array because both local fixture records are active.

ProjectPage and ProjectBriefPage are different presentations of one external resource. When both normalize the route input to the same ID and call useProject, they address the same detail entry in the same query cache.

For example, both routes for p-101 observe the entry identified by the detail query key. The brief can render a shorter view without receiving a copied Project through props, component state, or context.

Keep the route-specific presentation in each named page component. Each component normalizes its own route parameter, calls the same Hook, and renders directly from available query data. normalizeProjectId is the route-input helper established earlier; it returns string | null.

A successful query result has two separate timers.

• staleTime: how long the data is fresh after a successful read.
• gcTime: how long an inactive entry stays in the query cache after its last active consumer leaves.

For this demonstration, data is fresh for 30 s. If neither routed view is using an entry, that inactive entry is retained for 60 s before it can be removed.

These are intentionally short values for observing behavior locally, not universal production defaults.

Becoming stale does not delete data and does not independently start a request. Stale cached data remains available for rendering.

With the normal mount, window-focus, and reconnect behaviors enabled, a new consumer mount, returning focus, or reconnecting can refetch a stale entry. Those ordinary triggers do not refetch an entry that is still fresh.

An active consumer prevents the inactive-retention countdown. Age alone never causes garbage collection.

In src/main.tsx, replace the module-scope client construction. Keep the existing QueryClientProvider and routed application beneath this stable client.

A project can already be available from the query cache while TanStack Query performs another read. Do not replace that content with an initial-loading screen.

Use query.data !== undefined to keep rendering the last successful project. When query.isFetching is also true, add the restrained status Refreshing…. The overview and brief links remain usable during this background refresh.

Replace the result-rendering portion of the established ProjectPage with this pattern. It keeps a cached project visible before considering loading or unavailable-data UI.

Open browser DevTools before the experiment. In Network, filter for projects and enable Disable cache while DevTools remains open. This prevents the browser HTTP cache from hiding fixture reads; it does not clear TanStack Query's in-memory query cache.

Use a full browser reload when you need a cold query cache. For a more visible initial or background state, you may temporarily throttle the network.

After completing the condition, run the fresh, stale-retained, and collected-entry cases in your local app. Keep DevTools Network open with Disable cache enabled. Record observations rather than trying to match a fixed development request count.

A failed resource read is ordinary query state, not a rendering crash. Keep throwOnError: false so each routed view can render an expected recovery state. For this local demonstration, retry: 1 permits one managed retry after an unsuccessful read, and retryDelay: 1_000 waits 1 s before that retry.

The existing 30 s staleTime and 60 s gcTime settings remain in place. Mount, window-focus, and reconnect refetch behavior stays enabled because this configuration does not override it.

Replace src/main.tsx with this version. App remains the default export established earlier. The stable module-scope client now adds the bounded retry policy.

Handle expected HTTP, decoding, and validation failures from query state. A route-level error boundary still protects unexpected rendering failures, but it should not replace ordinary read-recovery UI.

For a valid project route, check query.data !== undefined before making a broad error return. An error with data means the latest background refresh failed; it does not mean the last successful project disappeared. Keep the invalid-link branch first, because it must not offer refetch for a null identifier.

Replace src/features/projects/ProjectPage.tsx with this version. Apply the same data-first error structure to ProjectBriefPage, while retaining its brief-specific successful presentation.

Use DevTools request blocking while the browser remains online. In Network, block the exact /data/projects/p-101.json request URL.

1. Open /projects/p-101 and perform a full reload for a cold query cache. Observe the completed failed read and the one managed retry about 1 s later before initial-error feedback appears.
2. A development StrictMode cycle can also produce a canceled entry. Identify it as cancellation; do not count it as a completed failed read or as the configured retry.
3. Unblock the URL and choose Try again.
4. After a successful Atlas load, block the URL again and choose Refresh. Then unblock it and choose Refresh once more.

Do not use offline mode for this experiment: it can pause a query rather than create the failed-read path being tested. Navigation cancellation is also not a recovery failure.

Your finished application has one read pipeline, not several copies of project state:

• main.tsx creates one module-scope QueryClient and places its provider above the routed app.
• public/data/ supplies the read-only JSON fixtures through Vite HTTP URLs.
• projectData.ts validates unknown JSON and rejects failed reads.
• projectQueries.ts turns normalized inputs into query keys and query functions.
• ProjectListPage, ProjectPage, and ProjectBriefPage present the query result for their route.

A route value becomes a normalized filter or projectId, then selects a query key. The query function reads and validates the resource. The query cache holds the result, and each route presents that result directly. Do not copy it into context or initialize component state from it.

A full browser reload starts a new in-memory query cache; ordinary route navigation does not.

Use your local app and the Network panel to collect concise evidence. Keep the earlier timing experiments as your reference; you do not need to repeat every wait.

For request observations, disable the browser HTTP cache in developer tools if you used that setting earlier. This helps expose network behavior but does not clear the in-memory query cache. A full reload does clear that cache.