Co-located TanStack Router, TanStack Query, and Shadcn Sidebar in Astro

Table of Contents

• Introduction
• Integrating TanStack Router
  • Installation
  • Configuration
• Setting Up TanStack Query
• Adding Shadcn Sidebar for Navigation
  • Installation
  • Configuration
• Conclusion
• References

Introduction

This guide covers integrating TanStack Router, TanStack Query, and Shadcn’s sidebar component into an Astro application. Versions current as of this update:

1
{
2
  "astro": "^7.3.3",
3
  "@tanstack/react-query": "^5.103.2",
4
  "@tanstack/react-router": "^1.170.38"
5
}

Tools used:

• Astro: a content-focused framework that ships zero JS by default and hydrates islands on demand.
• TanStack Router: a type-safe router that lets you co-locate route definitions with components.
• TanStack Query: async state management with caching, retries, and background refetching.
• Shadcn Sidebar: a composable, unstyled sidebar primitive you own the source of.

Integrating TanStack Router

TanStack Router supports a co-located routing approach: route files live next to the components they render. This keeps related code together instead of splitting it across a routes directory and a components directory.

Installation

1
pnpm add @tanstack/react-router @tanstack/router-plugin

@tanstack/router-plugin replaces the older @tanstack/router-vite-plugin package name. If you have the old package installed, remove it and install the renamed one.

Configuration

To produce a URL like https://example.com/dashboard, mirror the route in both TanStack Router’s route tree and Astro’s page directory:

Key points:

1. The TanStack Router side (the route file name, e.g. dashboard.tsx) drives what path segment the router matches at runtime.

2. The Astro side (the page folder, e.g. src/pages/dashboard/) drives what shows in the browser’s address bar. Keep the folder name consistent with the route so deep links resolve correctly.

3. Wire the router plugin into astro.config.mjs:

   Click to expand the code

   1
   // @ts-check
   2
   import { defineConfig } from "astro/config";
   3
   import remarkMath from "remark-math";
   4
   import rehypeKatex from "rehype-katex";
   5
   import partytown from "@astrojs/partytown";
   6
   import react from "@astrojs/react";
   7
   import { tanstackRouter } from "@tanstack/router-plugin/vite";
   8
   import mdx from "@astrojs/mdx";
   9
   import icon from "astro-icon";
   10
   import sitemap from "@astrojs/sitemap";
   11
   
   12
   // https://astro.build/config
   13
   export default defineConfig({
   14
     integrations: [
   15
       react(),
   16
       mdx(),
   17
       partytown({
   18
         // Forwards dataLayer.push calls from the main thread to the worker.
   19
         config: {
   20
           forward: ["dataLayer.push"],
   21
         },
   22
       }),
   23
       icon(),
   24
       sitemap(),
   25
     ],
   26
     vite: {
   27
       plugins: [
   28
         tanstackRouter({
   29
           target: "react",
   30
           routesDirectory: "./src/toolbox/routes",
   31
           generatedRouteTree: "./src/toolbox/routeTree.gen.ts",
   32
           routeFileIgnorePrefix: "-",
   33
           quoteStyle: "double",
   34
         }),
   35
       ],
   36
     },
   37
   });

   Tailwind 4 no longer uses @astrojs/tailwind or a tailwind.config.js. It integrates through the @tailwindcss/vite Vite plugin and a @import "tailwindcss"; line in your global CSS. If you followed the old Tailwind 3 setup, migrate that separately before wiring up the router.

Setting Up TanStack Query

1
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
2
import {
3
  ErrorComponent,
4
  RouterProvider,
5
  createRouter,
6
} from "@tanstack/react-router";
7

8
import { routeTree } from "./routeTree.gen";
9
import { Spinner } from "@/components/Spinner";
10

11
// Initialize QueryClient with default options
12
const queryClient = new QueryClient({
13
  defaultOptions: {
14
    queries: {
15
      retry: 5, // Number of retry attempts
16
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000), // Exponential backoff: 1s, 2s, 4s, etc.
17
      refetchOnWindowFocus: false, // Optional: disable refetch on window focus
18
    },
19
  },
20
});
21

22
// Create a new router instance
23
const router = createRouter({
24
  routeTree,
25
  defaultPendingComponent: () => (
26
    <div className="p-2 text-2xl">
27
      <Spinner />
28
    </div>
29
  ),
30
  defaultErrorComponent: ({ error }) => <ErrorComponent error={error} />,
31
  context: {
32
    queryClient,
33
  },
34
  defaultPreload: "intent",
35
  defaultPreloadStaleTime: 0,
36
});
37

38
// Extend TanStack Router's context to include our router
39
declare module "@tanstack/react-router" {
40
  interface Register {
41
    router: typeof router;
42
  }
43
}
44

45
export const Dashboard = () => (
46
  <QueryClientProvider client={queryClient}>
47
    <RouterProvider router={router} defaultPreload="intent" />
48
  </QueryClientProvider>
49
);

Adding Shadcn Sidebar for Navigation

Shadcn’s sidebar component gives you an accessible, composable navigation shell that you copy into your own codebase, so it slots into an Astro island without extra wrapper work.

Installation

1
pnpm dlx shadcn@latest add sidebar

Configuration

The VariantProps export from class-variance-authority is type-only. Astro’s Vite pipeline will fail the build if you import it as a value:

1
import { type VariantProps, cva } from "class-variance-authority";
2
// Rest of your sidebar component code...

Common error if the type keyword is missing:

1
[ERROR] [vite] The requested module 'class-variance-authority' does not provide an export named 'VariantProps'
2
  Stack trace:
3
    at node_modules/.pnpm/vite@.../node_modules/vite/dist/node/chunks/dep-*.js
4
    [...] See full stack trace in the browser, or rerun with --verbose.

Conclusion

This setup pairs Astro’s zero-JS-by-default pages with a fully client-routed toolbox section, giving visitors instant page loads everywhere except the interactive parts of the site. TanStack Router, TanStack Query, and Shadcn’s sidebar work well together because none of them fight Astro’s island model: they mount once inside a single React root and manage their own state from there.

If you are taking this into production, the next steps below cover auth, data and observability, and the newsletter is where the Astro SaaS boilerplate ships first.

References

• Co-located TanStack Router SPA in Astro