Updating React Query Cache with Presigned URLs

[OtaniToshiyuki]

setQueryData is not directly writing the response of registerImagePath or deleteImagePath

Instead, it writes a locally constructed object (newEntry) that includes a newly generated presigned URL

Questions

Does this approach violate the recommended usage of setQueryData?

Even though the presigned URL is generated by the server, it is not returned as part of the mutation response.

Is there a more idiomatic or recommended approach for handling presigned URLs with expiration, while avoiding unnecessary invalidation and regeneration?

https://tkdodo.eu/blog/practical-react-query#dont-use-the-querycache-as-a-local-state-manager

“Don’t use the query cache as a local state manager.
Use it only for optimistic updates or for writing data received from the backend.”

interface S3Image {
  path: string;
  presiginedUrl: string;
}

export const S3PresignedImageManager = ({ id }: { id: string }) => {
  const trpc = useTRPC();
  const queryClient = useQueryClient();

  const { data }: { data: S3Image[] } = useSuspenseQuery(
    trpc.image.getById.queryOptions({ id }),
  );

  const { mutateAsync: registerImagePath } = useMutation(
    trpc.image.registerPath.mutationOptions(),
  );
  const { mutateAsync: deleteImagePath } = useMutation(
    trpc.image.deletePath.mutationOptions(),
  );

  const onObjectUploaded = async (newEntry: S3Image) => {
    const { path } = newEntry;
    await registerImagePath({ id, path });

    queryClient.setQueryData(
      trpc.image.getById.queryKey({ id }),
      (prev) => (prev ? [...prev, newEntry] : [newEntry]),
    );
  };

  const onObjectDeleted = async ({ path }: { path: string }) => {
    await deleteImagePath({ id, path });

    queryClient.setQueryData(
      trpc.image.getById.queryKey({ id }),
      (prev) =>
        prev ? prev.filter((image) => image.path !== path) : undefined,
    );
  };

  return (
    <S3ImageManager
      images={data}
      uploadDirectory={buildImageS3Path(id)}
      onObjectUploaded={onObjectUploaded}
      onObjectDeleted={onObjectDeleted}
      label="image file"
    />
  );
};

[vincere-mori]

The tkdodo rule is about not using the cache as Redux for client-invented state. Your case isn't that. The presigned URL did originate server-side (S3 SDK generated it on upload), you're just stitching it back together because your registerPath mutation doesn't return it. That's a different problem.

The cleanest fix is to make registerImagePath return the new entry including the presigned URL, then setQueryData writes server-confirmed data:

const { mutateAsync: registerImagePath } = useMutation(
  trpc.image.registerPath.mutationOptions({
    onSuccess: (newEntry) => {
      queryClient.setQueryData(
        trpc.image.getById.queryKey({ id }),
        (prev) => prev ? [...prev, newEntry] : [newEntry],
      )
    },
  }),
)

If you can't change the server contract, what you have is fine — it's not violating the rule, the data is server-sourced. But you have a real problem with presigned URLs that the rule doesn't cover: expiration. If your URL TTL is shorter than how long a user might keep the page open, the cached URL goes stale and images break with no refetch triggered.

Two ways to handle that:

1. Set staleTime on the query to less than the URL TTL (e.g. URL valid 1h, staleTime: 30 * 60 * 1000). The query refetches before URLs expire.
2. Store only the path in the cache and resolve URLs on render via a separate useQuery per image with a short staleTime. More requests but URLs are always fresh.

For most apps option 1 is enough.

[mujtbabbas]

The issue with the current approach isn't setQueryData itself, it's what you're putting into the cache. A presigned URL is an expiring value, but it's being stored as if it were part of the entity data. Once it's baked into the getById list, React Query has no way to know that one field goes stale on a completely different clock from the rest of the data, so you end up with entries that look fresh while their URLs are already dead.

The idiomatic split is: the cache holds durable data, and the presigned URL is treated as derived data with its own lifetime.

1. Keep the entity list free of URLs. Let trpc.image.getById return the image records with their S3 path/key only. After a register or delete, updating this list with setQueryData is completely fine, just write the paths, not URLs.
2. Give the presigned URL its own query, keyed by the path:

const usePresignedUrl = (path: string) =>
  useQuery({
    queryKey: ['presignedUrl', path],
    queryFn: () => generatePresignedUrl(path), // your signing call
    staleTime: 1000 * 60 * 50, // safely under the URL's actual TTL
  });

Each rendered image resolves its URL through this query. React Query then refetches the URL before it expires, dedupes signing calls across components, and the URL lifetime is managed by staleTime instead of by you remembering to patch entity objects.

3. For the "show it immediately after upload" case, write the fresh URL into the URL query's cache entry, not into the entity:

queryClient.setQueryData(['presignedUrl', newPath], freshUrl);

That gives you the instant preview while keeping the two lifetimes separate. And if you'd rather not hand-maintain the list at all, invalidating getById after register/delete gets you the same correctness with one refetch; setQueryData is the optimisation, not a requirement.

In short: cache the path, query the URL. The expiry belongs to the URL, so the URL gets the query key.