{"id":8334,"date":"2026-01-23T10:51:50","date_gmt":"2026-01-23T15:51:50","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=8334"},"modified":"2026-01-28T09:27:37","modified_gmt":"2026-01-28T14:27:37","slug":"single-flight-mutations-in-tanstack-start-part-1","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/single-flight-mutations-in-tanstack-start-part-1\/","title":{"rendered":"Single Flight Mutations in TanStack Start: Part 1"},"content":{"rendered":"\n

A “single flight mutation”<\/strong> is a fancy way of saying: mutate the data and <\/em>update the UI with just one<\/em> round trip to the network.<\/p>\n\n\n\n

The beautiful thing about implementing this with TanStack is that we can leverage the tools we already know, and love: TanStack Query<\/a> (formerly react-query), TanStack Router<\/a>, and TanStack Start<\/a>.<\/p>\n\n\n\n

If you’re not familiar with these tools, TanStack Router is a client-only SPA framework (see my three-part introduction series<\/a>). TanStack Start is a server layer for Router that enables things like SSR, API routes, and server functions (see my introduction for it<\/a> and a post on its middleware feature<\/a>).<\/p>\n\n\n\n

I’ve never written about TanStack Query, but it’s one of the most widely used React libraries, and there are tons of resources about it. One of the best would be TkDodo’s blog<\/a>. He’s the lead maintainer of TanStack Query, and his blog is superb.<\/p>\n\n\n\n

In this first post, we’ll cover some fundamentals and then implement the simplest imaginable single flight mutation with a TanStack Start Server Function. In the next part, we’ll dive deep into middleware and implement a more serious solution, while having some fun with TypeScript in the process.<\/p>\n\n\n

\n
\n

Article Series<\/h3>\n <\/header>\n
\n
    \n
  1. \n Single Flight Mutations in TanStack Start: Part 1<\/a>\n <\/li>\n
  2. \n Single Flight Mutations in TanStack Start: Part 2<\/a>\n <\/li>\n <\/ol>\n <\/div>\n<\/div>\n\n\n\n

    Laying the Groundwork<\/h2>\n\n\n\n

    In my post on TanStack Start<\/a>, I included this image, which is how client-driven single-page applications (SPAs) almost always behave.<\/p>\n\n\n

    \n
    \"A<\/figure>\n<\/div>\n\n\n

    The initial request for whatever URL you’re viewing returns an empty skeleton of a page. From there, more networks requests happen to fetch scripts and styles, and most likely some data, which eventually results in your actual content page being rendered.<\/p>\n\n\n\n

    The network round trips will almost always be the single most expensive thing your web application will do. To look at it another way, there are few things you can do to improve performance as much as removing<\/em> network roundtrips. And this is why server-side rendering can be so beneficial: it allows us to display content to our users immediately<\/em>, after the initial request is responded to.<\/p>\n\n\n\n

    I expressed this in the Start post with this image.<\/p>\n\n\n

    \n
    \"Diagram<\/figure>\n<\/div>\n\n\n

    Those scripts and styles still have to load for your page to be interactive, but that initial response from the server can immediately display content for the user.<\/p>\n\n\n\n

    Why Single Flight Mutations<\/h2>\n\n\n\n

    Let’s think about how you’d normally update a piece of data in a web application.<\/p>\n\n\n\n

    You probably make a network request to some sort of \/update<\/code> endpoint, along with a post packet for whatever you’re trying to change. The endpoint will probably return a success flag, possibly with the actual piece of data you just updated. Your UI will usually then request updated data. You might think that returning the updated piece of data you just changed is all you’d need in order to update the UI, but frequently that’s not the case.<\/p>\n\n\n\n

    Imagine you’re looking at a list of TODO tasks, and you just edited one of them. Just updating the item on the screen isn’t good enough; maybe the edit causes this TODO to no longer even be in this list, depending on your filters. Or perhaps your edit causes this TODO to move to a different page in your results, based on your sort order. Or maybe you just created<\/em> a brand new<\/em> todo. In that case, who knows where, or even if<\/em> this todo will show up in your list, again based on your filters and sorts.<\/p>\n\n\n\n

    So we re-fetch whatever query produces our list. It usually looks like this<\/p>\n\n\n

    \n
    \"A<\/figure>\n<\/div>\n\n\n

    This works, and if we’re honest with ourselves, it’s usually good enough. But can we do better? We wouldn’t be good engineers if we didn’t at least try<\/em>. Conceptually we’d like to get something like this<\/p>\n\n\n

    \n
    \"A<\/figure>\n<\/div>\n\n\n

    We’ll implement a dead simple solution to this here in part 1, and then part 2 will discuss increasingly flexible ways of accomplishing it with middleware.<\/p>\n\n\n\n

    Our App<\/h2>\n\n\n\n

    As with prior posts about TanStack Start and Router, this post will use our cheap, simple, and frankly ugly Jira clone. Here’s a repo for it<\/a>. It’s a trivial app that runs on an SQLite database. The epics page looks like this:<\/p>\n\n\n

    \n
    \"Screenshot<\/figure>\n<\/div>\n\n\n

    As you can see, zero effort was put into the design. But there’s a few sources of data on the screen, which will help us implement single flight mutations: the main list of epics; the count of all epics (12) just above the list; and above that we have a summary list of epics, with the numbers of tasks therein.<\/p>\n\n\n\n

    This is the page we’ll be focusing on for this post. If you’re following along at home, you can run the app with npm run dev<\/code> and then visit http:\/\/localhost:3000\/app\/epics<\/a>.<\/p>\n\n\n\n

    Our queries for our list of epics and our summary data are driven by react-query. I’ve put the query options into helper utilities, like so.<\/p>\n\n\n

    export<\/span> const<\/span> epicsQueryOptions = (page<\/span>: number<\/span><\/span>) =><\/span> {\n  return<\/span> queryOptions({\n    queryKey: [\"epics\"<\/span>, \"list\"<\/span>, page],\n    queryFn: async<\/span> () => {\n      const<\/span> result = await<\/span> getEpicsList({ data: page });\n      return<\/span> result;\n    },\n    staleTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    gcTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n  });\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    This allows me to query data using the normal useQuery<\/code> or useSuspenseQuery<\/code> hook.<\/p>\n\n\n
    const<\/span> { data: epicsData } = useSuspenseQuery(epicsQueryOptions(deferredPage));<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    And also prefetch these queries in TanStack loaders, without duplicating code.<\/p>\n\n\n
      async<\/span> loader({ context, deps }) {\n    const<\/span> queryClient = context.queryClient;\n\n    queryClient.ensureQueryData(epicsQueryOptions(deps.page));\n    queryClient.ensureQueryData(epicsCountQueryOptions());\n  },<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    As you can see, this query (and all our other queries) are just straight calls to a single server function (getEpicsList<\/code> in this case), with the result passed through. This is a key detail that will come in handy in part 2.<\/p>\n\n\n\n
    Simplest Possible Single Flight Mutation<\/h2>\n\n\n\n
    Let’s implement a dirt simple single flight mutation, and then iterate on it, to make it more and more scalable. Our main epics page has an edit button, which allows for inline editing.<\/p>\n\n\n
    \n
    \"A<\/figure>\n<\/div>\n\n\n
    When we hit save, let’s just refetch the list of epics, as well as the epics summary data inside the edit epic server function, and send those new data down to the client, so the client can update the UI.<\/p>\n\n\n\n
    Here’s the entire server function:<\/p>\n\n\n
    export<\/span> const<\/span> updateWithSimpleRefetch = createServerFn({ method: \"POST\"<\/span> })\n  .inputValidator((obj<\/span>: { id<\/span>: number<\/span>; name<\/span>: string<\/span> }<\/span>) =><\/span> obj)\n  .handler(async<\/span> ({ data }) => {\n    await<\/span> new<\/span> Promise<\/span>(resolve<\/span> =><\/span> setTimeout(resolve, 1000<\/span> * Math<\/span>.random()));\n    await<\/span> db.update(epicsTable).set({ name: data.name }).where(eq(epicsTable.id, data.id));\n\n    const<\/span> [epicsList, epicsSummaryData] = await<\/span> Promise<\/span>.all([getEpicsList({ data: 1<\/span> }), getEpicsSummary()]);\n\n    return<\/span> { epicsList, epicsSummaryData };\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We save our epic, and then fetch the updated data from the getEpicsList<\/code>, and getEpicsSummary<\/code> server functions, which we call in parallel with Promise.all<\/code>. Note that a production-ready application would likely have some error handling.<\/p>\n\n\n\n
    Now when we call our server function, the data for those queries will be attached to the result. In fact, since we’re using server functions, these things will even be statically typed!<\/p>\n\n\n\n
    \"Code<\/figure>\n\n\n\n
    Updating the UI<\/h2>\n\n\n\n
    With updated data for our queries coming back after the save, we can now insert it back into the UI. TanStack Query makes this simple. We need a reference to the QueryClient:<\/p>\n\n\n
    const<\/span> queryClient = useQueryClient();<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Then we can update the query payload for a given query with the setQueryData<\/code> method. It takes the query key and the data.<\/p>\n\n\n
    const<\/span> handleSaveSimple = async<\/span> () => {\n  const<\/span> newValue = inputRef.current?.value || \"\"<\/span>;\n  const<\/span> result = await<\/span> runSaveSimple({\n    data: {\n      id: epic.id,\n      name: newValue,\n    },\n  });\n\n  queryClient.setQueryData([\"epics\"<\/span>, \"list\"<\/span>, 1<\/span>], result.epicsList);\n  queryClient.setQueryData([\"epics\"<\/span>, \"list\"<\/span>, \"summary\"<\/span>], result.epicsSummaryData);\n\n  setIsEditing(false<\/span>);\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    If hard-coding those query keys feels gross to you, don’t forget about those helper utilities we added before.<\/p>\n\n\n
    queryClient.setQueryData(epicsQueryOptions(1<\/span>).queryKey, result.epicsList, { updatedAt: Date<\/span>.now() });\nqueryClient.setQueryData(epicsSummaryQueryOptions().queryKey, result.epicsSummaryData, { updatedAt: Date<\/span>.now() });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Iterating<\/h2>\n\n\n\n
    Our solution works, but it’s fragile. Our server function hard codes which data to fetch. What if our update function were to be called from different parts of the UI, which each needed different slices of data to be refetched? We certainly don’t want to redefine our server function N times, for each place it needs to be called.<\/p>\n\n\n\n
    Fortunately, TanStack has the perfect feature to help reduce this coupling: Middleware. We can remove the refetching from the server function, and move it to a reusable middleware which can be attached to server functions.<\/p>\n\n\n
    \n  
    \n    
    Article Series<\/h3>\n  <\/header>\n  
    \n            
      \n                      
    1. \n              Single Flight Mutations in TanStack Start: Part 1<\/a>\n            <\/li>\n                      
    2. \n              Single Flight Mutations in TanStack Start: Part 2<\/a>\n            <\/li>\n                  <\/ol>\n        <\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
      What if we could mutate data *and* get all the data back we need to properly update the UI in just one network round-trip?<\/p>\n","protected":false},"author":21,"featured_media":8372,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1],"tags":[3,440,240,184],"class_list":["post-8334","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-javascript","tag-mutations","tag-tanstack","tag-typescript"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/frontendmasters.com\/blog\/wp-content\/uploads\/2026\/01\/tanstack-round-trip.jpg?fit=2000%2C1200&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8334","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/comments?post=8334"}],"version-history":[{"count":16,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8334\/revisions"}],"predecessor-version":[{"id":8418,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8334\/revisions\/8418"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media\/8372"}],"wp:attachment":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media?parent=8334"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/categories?post=8334"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/tags?post=8334"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}