Chapter 12: Architectural Patterns: Composing TanStack Libraries

Introduction: Building Harmonious Frontend Architectures

Welcome to Chapter 12! So far, we’ve explored individual TanStack libraries, diving deep into their unique superpowers. We’ve seen how TanStack Query masterfully handles server state, how TanStack Router streamlines navigation, and how TanStack Table and Virtual bring large datasets to life with impressive performance. But what happens when you bring them all together?

This chapter is all about composition. We’ll shift our focus from individual library mechanics to the art of weaving them into a cohesive, robust, and performant frontend architecture. Think of it like conducting an orchestra – each instrument (library) plays its part, but the magic truly happens when they play in harmony. We’ll explore common architectural patterns, understand how data flows through a TanStack-powered application, and discuss strategies for making informed design decisions.

By the end of this chapter, you’ll have a clearer mental model for integrating TanStack libraries, understanding the interplay between server state and client state, and building scalable applications that are a joy to develop and maintain. Get ready to elevate your TanStack expertise from individual mastery to architectural brilliance!

Core Concepts: The TanStack Ecosystem in Concert

Building a modern frontend application often involves managing complex data flows, user interactions, and UI states. The TanStack ecosystem provides a powerful suite of tools that, when composed correctly, can simplify these challenges significantly. Let’s explore the core principles of how these libraries interact.

The Central Role of TanStack Query

At the heart of many TanStack architectures lies TanStack Query (v5). It acts as the primary orchestrator for all server-side data interactions. When you combine it with other libraries, Query’s role becomes even more critical:

• Data Source for UI Components: TanStack Query feeds data to components like TanStack Table, TanStack Form, and any other UI element that displays server-derived information.
• Mutation Handler: When users interact with forms or buttons to create, update, or delete data, TanStack Query handles these mutations, providing optimistic updates and automatic cache invalidation.
• Offline Support & Caching: Its robust caching mechanisms ensure a snappy user experience, reducing loading spinners and providing data even with intermittent connectivity.

TanStack Router and Data Loading Strategies

TanStack Router (v1), with its powerful typed route loaders, provides an elegant solution for pre-fetching data before a component renders. This eliminates waterfall requests and ensures a smoother navigation experience.

How they work together:

1. A user navigates to a new route.
2. TanStack Router’s loader function is triggered.
3. Inside the loader, you use TanStack Query’s queryClient.ensureQueryData or queryClient.prefetchQuery to fetch the necessary data. This leverages Query’s caching, so if the data is already fresh, no network request is made.
4. The data is resolved by the router and made available to the route’s components.
5. The component renders, accessing the pre-loaded data, often resulting in an instant display without a loading state.

This pattern is incredibly powerful for “route-level” data requirements.

TanStack Form: Managing User Input and Server Interactions

TanStack Form (v0.20+) is designed to manage complex form states, validation, and submission logic. It shines when integrated with TanStack Query.

Synergy:

• Submission: Form submissions typically trigger a TanStack Query mutation. This allows you to leverage Query’s loading, error, and success states, as well as its automatic cache invalidation upon successful mutation.
• Initial Values: Forms can be pre-populated with data fetched via TanStack Query, ensuring consistency.
• Validation: While TanStack Form handles client-side validation, server-side validation errors can be easily integrated back into the form’s state.

TanStack Table & Virtual: Displaying Large Datasets Efficiently

When your application needs to display lists or tables with potentially thousands or even millions of rows, TanStack Table (v8) and TanStack Virtual (v3) are your best friends.

Collaboration:

• Table as the UI Layer: TanStack Table provides the headless logic for sorting, filtering, pagination, and grouping, giving you complete control over the UI rendering.
• Query as the Data Source: The data that populates TanStack Table often comes directly from TanStack Query, which handles fetching, caching, and re-fetching based on table state changes (e.g., sorting, pagination).
• Virtual for Performance: For truly massive datasets, TanStack Virtual wraps around the rendered rows of TanStack Table to ensure only the visible rows are actually in the DOM, drastically improving performance and memory usage.

TanStack Store: The Client-Side Companion

While TanStack Query handles server state, TanStack Store (v0.5+) is a lightweight, reactive, and immutable data store that can manage your client-side UI state. This is crucial for separating concerns.

When to use Store:

• Ephemeral UI states: Things like modal open/close status, active tab, selected items in a multi-select, or temporary user preferences that don’t need to persist or be synchronized with a server.
• Global configuration: Application-wide settings that are not fetched from the server.
• Derived state: Simple computations based on existing client-side state.

Why not use Query for everything? Query is optimized for asynchronous server data. Using it for purely client-side, synchronous UI state would be overkill and complicate your data flow. TanStack Store fills this gap perfectly.

The Ecosystem in Action: A Visual Overview

To help visualize how these pieces fit together, consider this simplified architectural diagram for a typical TanStack application:

Understanding the Flow:

1. User Interaction: The user interacts with the UI.
2. Routing: If the interaction involves navigation, TanStack Router takes over, potentially triggering Route Loaders.
3. Server State Management: Route loaders (or components directly) use TanStack Query to fetch or mutate server data. Query communicates with your Backend API.
4. Displaying Data: The data from TanStack Query then populates components like TanStack Table. For large datasets, TanStack Virtual steps in to optimize rendering.
5. User Input: When users submit data, TanStack Form manages the input, and its submission often triggers a TanStack Query mutation. Forms can also update URL parameters via TanStack Router for filtering or sorting.
6. Client-Side State: For purely local UI state (like modal visibility), TanStack Store provides a lightweight and reactive solution.
7. Reactivity: TanStack Query ensures that as server data changes (either through re-fetches or mutations), the UI automatically updates.

Architectural Decision Making: When to Use What?

A key aspect of good architecture is knowing which tool to use for which job.

• Server State: ALWAYS use TanStack Query. It handles caching, revalidation, retries, optimistic updates, and more, seamlessly.
• Client State (Global/Complex): Use TanStack Store for non-server-derived, application-wide UI state that needs to be reactive and shared across components.
• Client State (Local/Simple): For component-specific, transient UI state, stick to React’s useState or useReducer.
• Routing & URL Management: TanStack Router is your go-to for managing application routes, URL parameters (which can drive data fetching!), and navigation.
• Form Handling: TanStack Form provides robust typed solutions for managing user input, validation, and submission logic.
• Data Display: TanStack Table is for structured data displays.
• Performance for Large Lists: TanStack Virtual is essential when you have many items to render in a list or table, regardless of whether it’s TanStack Table or a custom list.

Step-by-Step Implementation: Building a Filterable, Paginated Table

Let’s put these concepts into practice by building a common scenario: a paginated and filterable data table that fetches data via TanStack Query, updates its state via TanStack Router’s search parameters, and is rendered with TanStack Table. We’ll keep it simple but demonstrate the core integration.

We’ll assume you have a basic React project set up with TanStack Query, Router, and Table already installed. If not, please refer to previous chapters for setup.

Current Versions (as of 2026-01-07):

• @tanstack/react-query: v5.x.x
• @tanstack/react-router: v1.x.x
• @tanstack/react-table: v8.x.x

1. Define Your Route and Search Params

First, we’ll define a route for our products table that accepts page, pageSize, and search as URL search parameters. These parameters will dictate what data TanStack Query fetches.

src/routes/products.tsx

// src/routes/products.tsx
import { createFileRoute, useNavigate } from '@tanstack/react-router';
import { z } from 'zod'; // For schema validation

// 1. Define the search parameter schema
const productsSearchSchema = z.object({
  page: z.number().catch(1), // Default to page 1
  pageSize: z.number().catch(10), // Default to 10 items per page
  search: z.string().catch(''), // Default to empty search string
});

export const Route = createFileRoute('/products')({
  // 2. Attach the search schema to the route
  validateSearch: productsSearchSchema,
  component: ProductsComponent,
  // 3. Optional: Define a loader to pre-fetch initial data
  //    For simplicity, we'll fetch directly in the component for this example,
  //    but for true pre-fetching, this is where you'd use queryClient.ensureQueryData
  // loader: async ({ context: { queryClient }, search }) => {
  //   await queryClient.ensureQueryData(productsQueryOptions(search));
  // },
});

// Dummy data type for our products
interface Product {
  id: number;
  name: string;
  price: number;
  category: string;
}

// Dummy API call function
const fetchProducts = async (page: number, pageSize: number, search: string): Promise<{ data: Product[]; total: number }> => {
  console.log(`Fetching products: page=${page}, pageSize=${pageSize}, search=${search}`);
  // Simulate API delay
  await new Promise(resolve => setTimeout(resolve, 500));

  const allProducts: Product[] = Array.from({ length: 100 }, (_, i) => ({
    id: i + 1,
    name: `Product ${i + 1}`,
    price: parseFloat((Math.random() * 100 + 10).toFixed(2)),
    category: i % 2 === 0 ? 'Electronics' : 'Books',
  }));

  const filteredProducts = allProducts.filter(p =>
    p.name.toLowerCase().includes(search.toLowerCase()) ||
    p.category.toLowerCase().includes(search.toLowerCase())
  );

  const start = (page - 1) * pageSize;
  const end = start + pageSize;
  const paginatedProducts = filteredProducts.slice(start, end);

  return { data: paginatedProducts, total: filteredProducts.length };
};

// TanStack Query options for our products
import { queryOptions, useQuery } from '@tanstack/react-query';

const productsQueryOptions = (searchParams: z.infer<typeof productsSearchSchema>) =>
  queryOptions({
    queryKey: ['products', searchParams], // Query key includes search params for uniqueness
    queryFn: () => fetchProducts(searchParams.page, searchParams.pageSize, searchParams.search),
  });

function ProductsComponent() {
  // 4. Access the search parameters from the route
  const { page, pageSize, search } = Route.useSearch();
  const navigate = useNavigate();

  // 5. Use TanStack Query to fetch data based on the search parameters
  const { data, isLoading, isError, error } = useQuery(productsQueryOptions({ page, pageSize, search }));

  // 6. Define handlers for changing pagination and search
  const setPage = (newPage: number) => {
    navigate({ search: { page: newPage, pageSize, search } });
  };

  const setPageSize = (newPageSize: number) => {
    navigate({ search: { page: 1, pageSize: newPageSize, search } }); // Reset to page 1 on page size change
  };

  const setSearch = (newSearch: string) => {
    navigate({ search: { page: 1, pageSize, search: newSearch } }); // Reset to page 1 on search change
  };

  if (isLoading) return <p>Loading products...</p>;
  if (isError) return <p>Error loading products: {error?.message}</p>;

  const products = data?.data || [];
  const totalProducts = data?.total || 0;
  const totalPages = Math.ceil(totalProducts / pageSize);

  return (
    <div className="p-4">
      <h2 className="text-2xl font-bold mb-4">Product Catalog</h2>

      {/* Search Input */}
      <input
        type="text"
        placeholder="Search products..."
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        className="border p-2 rounded mb-4"
      />

      {/* Product Table (simplified for now, TanStack Table integration next) */}
      <div className="border rounded-lg overflow-hidden shadow-md">
        <table className="min-w-full bg-white">
          <thead className="bg-gray-100">
            <tr>
              <th className="py-2 px-4 border-b">ID</th>
              <th className="py-2 px-4 border-b">Name</th>
              <th className="py-2 px-4 border-b">Price</th>
              <th className="py-2 px-4 border-b">Category</th>
            </tr>
          </thead>
          <tbody>
            {products.length === 0 ? (
              <tr>
                <td colSpan={4} className="text-center py-4 text-gray-500">No products found.</td>
              </tr>
            ) : (
              products.map((product) => (
                <tr key={product.id} className="hover:bg-gray-50">
                  <td className="py-2 px-4 border-b">{product.id}</td>
                  <td className="py-2 px-4 border-b">{product.name}</td>
                  <td className="py-2 px-4 border-b">${product.price.toFixed(2)}</td>
                  <td className="py-2 px-4 border-b">{product.category}</td>
                </tr>
              ))
            )}
          </tbody>
        </table>
      </div>

      {/* Pagination Controls */}
      <div className="flex justify-between items-center mt-4">
        <select
          value={pageSize}
          onChange={(e) => setPageSize(Number(e.target.value))}
          className="border p-2 rounded"
        >
          {[5, 10, 20, 50].map(size => (
            <option key={size} value={size}>{size} per page</option>
          ))}
        </select>
        <div>
          <button
            onClick={() => setPage(page - 1)}
            disabled={page === 1}
            className="px-3 py-1 border rounded mr-2 disabled:opacity-50"
          >
            Previous
          </button>
          <span className="mx-2">Page {page} of {totalPages}</span>
          <button
            onClick={() => setPage(page + 1)}
            disabled={page === totalPages}
            className="px-3 py-1 border rounded disabled:opacity-50"
          >
            Next
          </button>
        </div>
      </div>
    </div>
  );
}

Explanation:

1. We define a zod schema productsSearchSchema to validate and type our URL search parameters (page, pageSize, search). This is a key feature of TanStack Router for type safety.
2. createFileRoute('/products') defines our route, and validateSearch links our schema, ensuring all search params are parsed and typed correctly.
3. We’ve set up a fetchProducts function that simulates an API call, including filtering and pagination logic. This will be our data source.
4. productsQueryOptions is a helper for queryOptions from TanStack Query. Notice how the queryKey includes the searchParams. This is crucial: when any search parameter changes, TanStack Query sees a new queryKey and automatically refetches the data.
5. Inside ProductsComponent, Route.useSearch() gives us direct access to the parsed and typed URL search parameters.
6. useQuery then uses these parameters to fetch data.
7. The setPage, setPageSize, and setSearch functions use navigate from TanStack Router to update the URL’s search parameters. Crucially, this automatically triggers a re-fetch by TanStack Query because the queryKey changes, and the UI updates with the new data.

2. Integrate TanStack Table for Enhanced UI

Now, let’s replace our simple HTML table with the powerful TanStack Table. This will give us more control over column definitions, sorting, and future features.

src/routes/products.tsx (modifications to ProductsComponent)

// ... (previous imports and code)
import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  createColumnHelper,
} from '@tanstack/react-table';

// ... (Product interface, fetchProducts, productsQueryOptions remain the same)

// Create a column helper for type safety
const columnHelper = createColumnHelper<Product>();

function ProductsComponent() {
  const { page, pageSize, search } = Route.useSearch();
  const navigate = useNavigate();

  const { data, isLoading, isError, error } = useQuery(productsQueryOptions({ page, pageSize, search }));

  const setPage = (newPage: number) => {
    navigate({ search: { page: newPage, pageSize, search } });
  };

  const setPageSize = (newPageSize: number) => {
    navigate({ search: { page: 1, pageSize: newPageSize, search } });
  };

  const setSearch = (newSearch: string) => {
    navigate({ search: { page: 1, pageSize, search: newSearch } });
  };

  // Define columns for TanStack Table
  const columns = [
    columnHelper.accessor('id', {
      header: 'ID',
    }),
    columnHelper.accessor('name', {
      header: 'Product Name',
    }),
    columnHelper.accessor('price', {
      header: 'Price',
      cell: info => `$${info.getValue().toFixed(2)}`,
    }),
    columnHelper.accessor('category', {
      header: 'Category',
    }),
  ];

  const table = useReactTable({
    data: data?.data || [], // Provide data from TanStack Query
    columns,
    getCoreRowModel: getCoreRowModel(),
  });

  if (isLoading) return <p>Loading products...</p>;
  if (isError) return <p>Error loading products: {error?.message}</p>;

  const products = data?.data || [];
  const totalProducts = data?.total || 0;
  const totalPages = Math.ceil(totalProducts / pageSize);

  return (
    <div className="p-4">
      <h2 className="text-2xl font-bold mb-4">Product Catalog</h2>

      {/* Search Input */}
      <input
        type="text"
        placeholder="Search products..."
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        className="border p-2 rounded mb-4"
      />

      {/* TanStack Table Integration */}
      <div className="border rounded-lg overflow-hidden shadow-md">
        <table className="min-w-full bg-white">
          <thead className="bg-gray-100">
            {table.getHeaderGroups().map(headerGroup => (
              <tr key={headerGroup.id}>
                {headerGroup.headers.map(header => (
                  <th key={header.id} className="py-2 px-4 border-b text-left">
                    {header.isPlaceholder
                      ? null
                      : flexRender(header.column.columnDef.header, header.getContext())}
                  </th>
                ))}
              </tr>
            ))}
          </thead>
          <tbody>
            {table.getRowModel().rows.length === 0 ? (
              <tr>
                <td colSpan={columns.length} className="text-center py-4 text-gray-500">No products found.</td>
              </tr>
            ) : (
              table.getRowModel().rows.map(row => (
                <tr key={row.id} className="hover:bg-gray-50">
                  {row.getVisibleCells().map(cell => (
                    <td key={cell.id} className="py-2 px-4 border-b">
                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
                    </td>
                  ))}
                </tr>
              ))
            )}
          </tbody>
        </table>
      </div>

      {/* Pagination Controls (remain the same) */}
      <div className="flex justify-between items-center mt-4">
        <select
          value={pageSize}
          onChange={(e) => setPageSize(Number(e.target.value))}
          className="border p-2 rounded"
        >
          {[5, 10, 20, 50].map(size => (
            <option key={size} value={size}>{size} per page</option>
          ))}
        </select>
        <div>
          <button
            onClick={() => setPage(page - 1)}
            disabled={page === 1}
            className="px-3 py-1 border rounded mr-2 disabled:opacity-50"
          >
            Previous
          </button>
          <span className="mx-2">Page {page} of {totalPages}</span>
          <button
            onClick={() => setPage(page + 1)}
            disabled={page === totalPages}
            className="px-3 py-1 border rounded disabled:opacity-50"
          >
            Next
          </button>
        </div>
      </div>
    </div>
  );
}

Explanation:

1. We import useReactTable, getCoreRowModel, flexRender, and createColumnHelper from @tanstack/react-table.
2. createColumnHelper<Product>() provides a type-safe way to define our table columns.
3. The columns array defines how each piece of Product data maps to a table column, including custom cell rendering for the price.
4. useReactTable is initialized with the data coming directly from our useQuery hook and our columns definition. getCoreRowModel() is essential for basic table functionality.
5. The HTML table structure is updated to use table.getHeaderGroups().map(...) and table.getRowModel().rows.map(...) to render the table dynamically based on TanStack Table’s internal state. flexRender is used to render the header and cell content defined in our columns.

Now, when you navigate to /products in your application, you’ll see a table that:

• Fetches data based on page, pageSize, and search parameters from the URL.
• Updates the URL (and thus triggers a re-fetch) when you change the page, page size, or search term.
• Renders efficiently using TanStack Table’s headless logic.

This example beautifully demonstrates the synergy between TanStack Router (managing URL state), TanStack Query (fetching and caching server state), and TanStack Table (rendering the UI).

Mini-Challenge: Adding a “Clear Filters” Button

Your challenge is to add a “Clear Filters” button to the ProductsComponent. When clicked, this button should reset the search parameter to an empty string and the page parameter back to 1, while keeping the pageSize as is.

Challenge: Implement a button that, when clicked, clears the search input and resets the pagination to the first page. Place it near the search input.

Hint: You’ll need to use the navigate function from useNavigate and update the search object with new values. Remember to keep pageSize intact.

What to observe/learn:

• How easily you can manipulate URL search parameters using navigate.
• How changes to URL search parameters automatically trigger TanStack Query re-fetches.
• The reactive nature of the entire setup.

// Add this snippet inside ProductsComponent, near your search input:
// <input ... /> element
<button
  onClick={() => setSearch('')} // You'll need to modify setSearch to also reset the page
  className="ml-2 px-3 py-2 border rounded bg-gray-200 hover:bg-gray-300"
>
  Clear Search
</button>

// Modify your setSearch function to also reset the page
const setSearch = (newSearch: string) => {
  navigate({ search: { page: 1, pageSize, search: newSearch } }); // Reset to page 1 on search change
};

Go ahead and try it! Observe how the URL changes and the table instantly updates.

Common Pitfalls & Troubleshooting

Even with the best tools, architectural decisions can lead to challenges.

1. “Prop Drilling” vs. Global State:

   • Pitfall: Passing queryClient or similar global objects down many layers of components. This can make your component tree messy and hard to refactor.
   • Solution: For queryClient, it’s typically provided via a QueryClientProvider at the root, making it globally accessible via useQueryClient. For truly global client-side state, TanStack Store is designed to avoid prop drilling for non-server data. Use createContext for highly specific, localized global state.

2. Over-fetching/Under-fetching with Router Loaders:

   • Pitfall: Fetching too much data in a router loader (e.g., fetching data for deeply nested components not immediately visible) or not fetching enough (leading to loading spinners after the route has loaded).
   • Solution: Route loaders should fetch only the data necessary for the immediate route and its primary components. Use TanStack Query hooks within sub-components for data specific to those components or for data that can load asynchronously without blocking the initial route render. Leverage queryClient.ensureQueryData in loaders to ensure data is present, but let useQuery hooks handle subscription and freshness in components.

3. Mixing Server and Client State Inappropriately:

   • Pitfall: Using useQuery for purely client-side state (e.g., useState replacements) or trying to manage complex server-side caching with TanStack Store.
   • Solution: Remember the clear separation:
     • TanStack Query: Server state (async, caching, revalidation, mutations).
     • TanStack Store: Client state (sync, reactive, UI-specific, non-persistent global state).
     • useState/useReducer: Local component state (transient, encapsulated).
   • A common pattern is that data fetched by TanStack Query might influence client state managed by TanStack Store (e.g., a list of users from Query might populate a dropdown, and the selection from that dropdown is client state in Store).

Summary: Your Architectural Toolkit

You’ve now seen how the individual strengths of TanStack libraries combine to form a powerful and cohesive architectural pattern for modern web applications.

Here are the key takeaways:

• TanStack Query is the central nervous system for all server-side data, handling fetching, caching, and mutations across the application.
• TanStack Router manages navigation and uses typed search parameters to drive data fetching via Query, enabling robust URL-as-state patterns and pre-fetching.
• TanStack Table provides headless logic for complex data grids, efficiently displaying data sourced from Query.
• TanStack Virtual integrates with Table (or any list) to ensure high performance even with massive datasets by only rendering visible elements.
• TanStack Form streamlines user input, validation, and submission, often triggering Query mutations for server updates.
• TanStack Store complements Query by managing purely client-side UI state, ensuring a clear separation of concerns.
• Architectural harmony is achieved by understanding each library’s purpose and how they interact to manage data flow, user interaction, and UI rendering efficiently.

Congratulations! You’re now equipped with a deeper understanding of how to architect sophisticated frontend applications using the TanStack ecosystem. This knowledge will empower you to build scalable, maintainable, and highly performant user experiences.

What’s Next?

In the next chapter, we’ll delve into Chapter 13: Performance Optimization and Debugging. We’ll explore advanced techniques for ensuring your TanStack applications are blazing fast and how to effectively troubleshoot issues when they arise. Get ready to fine-tune your creations!

References

• TanStack Query Docs
• TanStack Router React Docs
• TanStack Table Docs
• TanStack Form Docs
• TanStack Virtual Docs
• TanStack Store Docs

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.