Sideload / Parallel Loaders

[jamesarosen]

Executive Summary

shouldRevalidate offers fine-grained control for loader data, but it only operates at the route level. If an app needs fine-grained control over when a specific piece of data revalidates, it must isolate that data in a separate route. This results in engineers having to make a tradeoff between UX and DX: either the resources are isolated and cached independently or the route tree grows impossibly long.

Problem

First steps

Imagine building an e-commerce site. At first, the root route's loader has just some global data in it:

// ~/root.tsx
export function loader({ context }) {
  return json({ env: context.env })
}

This is a small amount of data that rarely changes, so the default shouldRevalidate logic works well.

Add some data

We get a new requirement: the page navigation bar should have a list of 5 trending items. The trending list is context-sensitive: if we're looking at accessories, it should be a list of accessories. We add that to the root loader:

// ~/root.tsx
export function loader({ context, params }) {
  const category = params.category || 'all'
  const trendingProducts = await context.api.trendingProducts(category)
  return json({ env: context.env, trendingProducts })
}

Since the list is category-specific, we now need to revalidate the root data any time the category changes:

// ~/root.tsx
export function shouldRevalidate({ currentParams, defaultShouldRevalidate , nextParams }) {
  const currentCategory = currentParams.category || 'all'
  const nextCategory = nextParams.category || 'all'

  return currentCategory !== nextCategory || defaultShouldRevalidate
}

We can load this data in our navbar with useRouteLoaderData:

// ~/components/layout/NavBar/TrendingProducts.tsx

export function TrendingProducts() {
  const { trendingProducts } = useRouteLoaderData('root')
  return <ul>{trendingProducts.map(p => <li key={p.id}>{p.name}</li>)}</ul>
}

Add more data

Over time, we get more requirements for global data: the page header also needs the user's recent orders, support tickets, toast messages, ...

Eventually, we end up with a fairly large loader object:

// ~/root.tsx
export function loader({ context, params }) {
  ...
  return json({
    env: context.env,
    recentOrders,
    recentlyViewedProducts,
    session,
    supportTickets,
    toastMessages,
    trendingProducts,
  })
}

UX up, DX down

As the loader has grown, the logic for shouldRevalidate has gotten both increasingly complex and increasingly likely to return true. Switching from one category to another causes the loader to revalidate supportTickets even though that data isn't category-specific. This puts extra load on our servers and adds delay to page transitions.

Remix gives us an out: because shouldRevalidate is tied to a route, we can extract data that changes at a different rate to its own route. Let's start with trending products:

// ~/routes/_trendingProducts.tsx
export function shouldRevalidate({ currentParams, defaultShouldRevalidate , nextParams }) {
  const currentCategory = currentParams.category || 'all'
  const nextCategory = nextParams.category || 'all'
  return currentCategory !== nextCategory || defaultShouldRevalidate
}

export function loader({ context, params }) {
  const category = params.category || 'all'
  const trendingProducts = await context.api.trendingProducts(category)
  return json({ trendingProducts })
}

Remix can now revalidate /?_data={routes/_trendingProducts} independently.

We need to make one simple change to our <TrendingProducts> component to match:

// ~/components/layout/NavBar/TrendingProducts.tsx

export function TrendingProducts() {
  const { trendingProducts } = useRouteLoaderData('routes/_trendingProducts')
  return <ul>{trendingProducts.map(p => <li key={p.id}>{p.name}</li>)}</ul>
}

But now our app doesn't load, complaining that undefined.map is not a function. That's because _trendingProducts isn't in the route hierarchy for any of our pages. So for any page that needs this component (which is all of them, since it's in the main navbar), we need to insert _trendingProducts into the route hierarchy:

app/
  routes/
    _trendingProducts._index.tsx
    _trendingProducts.login.tsx
    _trendingProducts.categories.$categoryID.tsx
    _trendingProducts.products.$productID.tsx

And if we want to separate more root loader data out, the problem gets worse:

app/
  routes/
    _recentOrders._supportTickets._trendingProducts._index.tsx
    _recentOrders._supportTickets._trendingProducts.login.tsx
    _recentOrders._supportTickets._trendingProducts.categories.$categoryID.tsx
    _recentOrders._supportTickets._trendingProducts.products.$productID.tsx

This is reminiscent of the React Context "Flying V":

<RecentOrdersProvider>
  <SupportTicketsProvider>
    <TrendingProductsProvider>
      <Outlet />
    </TrendingProductsProvider>
  </SupportTicketsProvider>
</RecentOrdersProvider>

Proposals

Proposal 1: Side Loads

Allow routes to declare a list of side-loads:

// ~/root.tsx
export function sideLoads() {
  return [ 'recentOrders', 'supportTickets', 'trendingProducts' ]
}

This will cause Remix to do the following:

1. Remix attaches the list of side-load routes to each RouteMatch
2. during a hard-land (with SSR), Remix computes the set of all side-loads for all routes in the current request and adds them to the match data
3. during a transition, Remix fetches any side-loads that need to be fetched.
   • A side-load needs to be fetched if it appears in the next matches but didn't appear in any of the current matches
   • A side-load needs to be fetched if it appears in both the current and next matches and its shouldRevalidate returns true
   • A side-load does not need to be fetched if it doesn't appear in any of the next matches

Proposal 2: Compacted Layouts

Because side-loads aren't in the path hierarchy, they can't participate in the React DOM hierarchy. Importantly, they can't declare context providers. It might be nice to be able to do this:

// ~/routes/_trendingProducts.tsx
const TrendingProductsContext = createContext<Product[]>([])

// shouldRevalidate and loader from above

export default function TrendingProductsProvider() {
  const trendingProducts = useLoaderData()
  return (
    <TrendingProductsContext.Provider value={trendingProducts}>
      <Outlet />
    </TrendingProductsContext.Provider>
  )
}

The problem, then, is how to shrink _recentOrders._supportTickets._trendingProducts down. Ideally, we could shrink them all the way to a single declaration within the root route:

// ~/root.tsx
const RootLayout = composedLayout('recentOrders', 'supportTickets', 'trendingProducts')
export { loader: RootLayout.loader, default: RootLayout.default }

[jamesarosen]

@ryanflorence wrote

Our goal as we iterate from v2 to v3 is to make these use cases easier, but also decrease the API surface area of Remix, not increase it with more concepts.

This suggests a third option: expose more of the router, route-matcher, and revalidator as framework concepts. This would allow for both the side-loading and the layout-composition approaches to be implemented as plugins rather than as framework code.

[abelsj60]

@jamesarosen asked me to post a comment from Discord with @ryanflorence in this discussion, which I'm happy to do.

I should note a couple things first, though:

• @sergiodxa also has a proposal on "parallel routes," which seems to be a very similar issue at heart.
  • Sibling Routes (aka Parallel Routes or Aggregated Routes) #5431
• I've been wrestling with this topic a lot on my own application, which I'll gladly talk about another time. The bottom line, however, is that I need to manage stuff on screen that doesn't track the physical URL that we all see in our browser address bar.

My personal conclusion as to this pattern, however, is the following:

It's as broad as the browser and I'm not sure a use case fully covers what's needed. Sometimes this doesn't matter, but, in this case, I do have the creeping concern that, if this general idea is accepted, care should be taken to examine it from beyond any one use case.

Personally, I see the issue here as a browser/platform limitation. Sometimes, you want all the "platform" benefits of a URL without actually having a physical URL in the address bar. In other words, I've come to view this problem as one of real estate.

The browser only gives the developer one address bar to work with, so it arbitrarily limits the conversation.

Remix is in a somewhat unique position to bridge the gap.

What I've decided to do, in a very narrow way, is to employ the concept of a "logical URL." This means a URL that I can feed to my app outside of the address bar. It is tied to a resource route. As a URL, I can work with it like a URL without being limited to the browser's concept of "physical space." Put simply, I can now pair a physical URL with many logical URLs at once.

As you can imagine, one positive is that I can take this concept as far as I want.

For example, the resource route can pick its component and offer actions and loaders for it. It can go further, too. The resource route can allow for form-driven, or intent-driven, siblings/children. In this case, rather than an action with a switch statement for different mutation types, the developer could branch each form/intent into an entirely separate resource-route action: 

• /resources/time/start
• /resources/time/set
• /resources/time/end

There's a lot that can be done with this — using many of the same patterns as the Web and Remix, but without the physical limitations of a single dimension.

The downside for me is that I have to find ways around Remix's expectations to make this work. In another world, a future version of Remix could allow a type of export default component (as well as error/catch boundaries, action/loader revalidations, and a sort of <LogicalUrlOutlet />) via a resource-route construct (perhaps this concept could be renamed "logical route" or be given a "logical route" sibling).

My take is that this general idea is the best path forward for "parallel routes," as the spirit of the API surface would remain constant and its flexibility would be greatly increased. Anyway, I leave all that to everyone else.

For now, here's the conversation and code James asked me to post:

ryan: pathless routes don't have a URL, so you can't revalidate them 😅
...
me: Why not? I'm working my way down this path, one heavy step at a time. My ideas are 
juvenile, always, but why not something along the lines of this (this is untested and totally pseudocode):

__pathless.tsx
loader() { 
  let data;
  switch (formData.parsed.intent)
    case 'revalidate': { data = revalidateLogic() }
    default: { data = initialLoadLogic() }
  return json(data);
}

export function usePathlessRevalidate(path: string) {
  const fetcher = useFetcher();
  const [run, setRun] = React.useState();
  
  React.useEffect(() => {
    if (run) {
      fetcher.load({ intent: 'revalidate' }, { action: path, method: 'get' });
      setRun(false);
    }
  }, [run, fetcher, setRun, path]);

  return [run, setRun, fetcher?.data];
}

export default function() {
  const initData = useLoaderData();
  const [run, setRun, data] = usePathlessRevalidate('routes/__pathless');
  ...

  return <Outlet context={{ data, setRun }} />;
}

routeSegment.tsx
  ...
  export default function() {
    const { setRun } = useOutletContext();
    const handleClick = () => {
      ...
      setRun(true);
    }
    // (Or push this final setRun to trigger when some other fetcher is complete via a useEffect or via useRemixFetcher, which takes callbacks. Ish.)
    ...
  }

Src: https://discord.com/channels/770287896669978684/770287896669978687/1101552612903485620

-j