How to Structure Start + Query in the best way possible (Performance, Loading, Usability, ...)?

[jofflin]

Hi folks,
I got a pretty widespread question which is maybe also a share your structure or docs page type of question.
My Setup: I use Tanstack Start and Tanstack Query (and a lot of other packages, which are not important here).
What am I trying to find out: How to properly setup my structure regarding data fetching and caching with start + query. I already read through most of query, router and start docs but I find it difficult to understand a clear approach on how do to it.
I got a separate API which provides a openapi json and from there I generate with heyApi types, zod schemas for DTOs, fetch methods and query helpers (https://heyapi.dev/).
General Structure in my App. is I have a overview page and a detail page. All in the context of a ticketing platform (https://app.nono-events.de)
Example: Discount/Coupon feature:
I have the following:

• Zod Response: zListDiscountsData
• Fetch Method: listDiscounts
• Tanstack query options: listDiscountsOptions (this wraps the fetch method and does things like query keys automatically for all endpoints)
  Now I use this for the overview page to show a list of discounts. In the details I have a endpoint to fetch the discount details and then a list of discount usages.

The page for discount:

import { listDiscountsOptions } from '@nono/api-client/generated/@tanstack/react-query.gen';
import { zListDiscountsData } from '@nono/api-client/generated/zod.gen';
import { createMetadata } from '@nono/seo/metadata';
import { useSuspenseQuery } from '@tanstack/react-query';
import { createFileRoute } from '@tanstack/react-router';
import type { HeaderBreadcrumbItem } from '@/components/layout/types';
import { CouponsOverview } from '@/features/coupons';
import { m } from '@/lib/paraglide/messages';

export const Route = createFileRoute('/manage/discounts/')({
  component: RouteComponent,
  validateSearch: zListDiscountsData.shape.query
    .omit({ organizationId: true })
    .nonoptional(),
  loaderDeps: ({ search }) => search,
  loader: async ({ context, deps }) => {
    await context.queryClient.ensureQueryData(
      listDiscountsOptions({
        query: {
          ...deps,
          organizationId: context.organizationId,
        },
      })
    );
    return {
      organizationId: context.organizationId,
      breadcrumb: [
        {
          label: m.coupons_discounts_title(),
          href: '/manage/discounts',
        },
      ] as HeaderBreadcrumbItem[],
    };
  },
  head: ({ match }) => ({
    meta: createMetadata({
      title: m.coupons_discounts_title(),
      url: match.pathname.toString(),
    }),
  }),
});

function RouteComponent() {
  const { organizationId } = Route.useLoaderData();
  const query = Route.useSearch();
  const { data: discounts } = useSuspenseQuery(
    listDiscountsOptions({
      query: {
        ...query,
        organizationId,
      },
    })
  );
  return <CouponsOverview coupons={discounts.data} />;
}

You see: I do search with validateSearch and the in the loader loading the data. In the component I then do the useSuspensequery and pass the final, always set data to the dedicated Page/Component.

For settings the queryParams I defined a hook to set the params for the paginated search. This isnt the most typesafe appraoch but with 50+ paginated routes I dont want to do that much repetetive work.

import { useNavigate, useSearch } from '@tanstack/react-router';
import { useCallback } from 'react';
import { cleanEmptyParams } from '../utils/clean-empty-params';

export function useFilters() {
  const navigate = useNavigate();
  const filters = useSearch({ strict: false });

  const setFilters = useCallback(
    (partialFilters: Partial<typeof filters>) => {
      navigate({
        to: '.',
        search: (prev) => cleanEmptyParams({ ...prev, ...partialFilters }),
      });
    },
    [navigate]
  );

  const resetFilters = useCallback(() => {
    navigate({ to: '.', search: {} });
  }, [navigate]);

  const resetFilter = useCallback(
    (filterKey: string) => {
      navigate({
        to: '.',
        search: (prev) => cleanEmptyParams({ ...prev, [filterKey]: undefined }),
      });
    },
    [navigate]
  );

  return { filters, setFilters, resetFilters, resetFilter };
}

So to come to the end:

1. What is the 'best' way to update the search params. I am not happy with my current approach.
2. How do I fetch data correctly with start + query setup. I looked at the example but it does not provide clear information/guidance on why or how to use correctly. Is my approach await ensureQueryData and the useSuspenseQuery the way to go or how should it be handled properly.
3. On the details page is ensure the coupon data and then normally (with UseQuery) load the usages to not block the rendering for non-critical information. Is there any guidance/information/best practise on when/how to use the data fetching for these different screnarios.
4. As far as I understood I want to use the caching from query because of auto reloading. Example: I put the organizationId in the loaderData. the Id come from a ensureQueryData but then the user changes the org from orgA to orgB, the orgId stays still on the orgA ID. Thats why I go with query for caching.

I am really thankful for any input/comment or a link for existing discussions/docs.

What I found:
#1563

[jofflin]

Maybe a minor addition to the search params part.
At the moment we have the following structure for paginated/filtered data: Only preserved in search params. So user navigates to discounts, filters, then navigates to orders then again to discounts. In this case, we have no filters set because it is a new route that was pushed and not navigated back. What is the got approach here. Is there something that preserves the state for routes or should I use something like zustand to preserve while navigating on the platform?