tanstack-table-route

An opinionated library that leverages TanStack Router, TanStack Query, and TanStack Table to take care of the routing, loading, and caching infrastructure for a filtered, sorted, and paginated table of data served by an API of your choice and shown in a React table component of your choice.

Installation

To use this library in your project, install the npm package 'tanstack-table-route':

pnpm add tanstack-table-route

yarn add tanstack-table-route

npm install tanstack-table-route

Usage

This library provides the fspRouteOptions function. This function returns an options object that can be passed to the createRoute function for code-based routing or the createFileRoute for file-based routing. Both functions should be called with an options object. Some of these options are required and some are optional.

Code-Based FSP Routing

To specify a code-based FSP table route, you need to use the fspRouteOptions function in conjunction with the createRoute function as shown in the following example:

import { createRoute } from '@tanstack/react-router'
import { fspRouteOptions } from 'tanstack-table-route'

const tasksIndexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/items',
  ...fspRouteOptions({
    component: Items,
    queryURLBuilder: (params: FSPParams) => drfQueryURLBuilder(API_BASE_URL, params),
  }),
})

File-Based FSP Routing

To specify a file-based FSP table route, you need to use the fspRouteOptions function in conjunction with the createFileRoute function as shown in the following example:

import { createFileRoute } from '@tanstack/react-router'
import { fspRouteOptions } from 'tanstack-table-route'

export const Route = createFileRoute(path)(
  fspRouteOptions({
    component: Items,
    queryURLBuilder: (params: FSPParams) => drfQueryURLBuilder(API_BASE_URL, params),
    parseData: function (rawTask: RawTaskData): TaskData {
      const { created_at, completed_at, ...restData } = rawTask
      return {
        created_at: new Date(created_at),
        completed_at: completed_at ? new Date(completed_at) : null,
        ...restData,
      }
    },
  })
)

Options

The options provided to the fspRouteOptions function are:

• component: The React component that renders the filtered, sorted, and paginated table. This component receives the props specified in FSPComponentProps. This component is wrapped in a component that provides the necessary context for the table to work, i.e., it takes care of querying the appropriate page of data based on the filtering, sorting, and pagination parameters. The wrapping component is included in the underlying TanStack Router options.
• queryURLBuilder: A function that builds the API URL from which to fetch the filtered and sorted page of items as specified in the given query parameters and based on the given base URL.
• parseData: Optional function that parses a raw data object as fetched from the API server and returns a data object with properties of the desired types. These parsed data objects are provided to the table component (and cached by TanStack Query).
• errorComponent: Optional React component that renders when an error occurs. A default is provided. Included in the underlying TanStack Router options.
• pendingComponent: Optional React component that renders while the route is loading. A default is provided. Included in the underlying TanStack Router options.

Enabling Auto-CodeSplitting in the TanStack Router Vite Plugin

If you want to enable the autoCodeSplitting option in the TanStack Router plugin for Vite, you will also need to adjust your use of the fspRouteOption helper due to limitations in this plugin.

The plugin uses static analysis to identify the chunking targets. To be able to do so, it needs the options for the createFileRoute function to be explicitly expressed in the code. To achieve this, you must destructure the results of the fspRouteOption helper and provide them as key-value options to the createFileRoute function, as shown in the following rewritten example.

const {
  component,
  loader,
  loaderDeps,
  pendingComponent,
  errorComponent,
  validateSearch,
} = fspRouteOptions({
  component: Tasks,
  queryURLBuilder: (params: FSPParams) => drfQueryURLBuilder(API_BASE_URL, params),
})
export const Route = createFileRoute('/tasks/')({
  component,
  loader,
  loaderDeps,
  pendingComponent,
  errorComponent,
  validateSearch,
})

Examples

The sourcecode for this project is maintained in a monorepo that also contains two fully functioning demo applications with a Mantine-based frontend and a DRF-based API backend.