🗺️ Client Data (clientLoader, clientAction)

[ryanflorence]

Client Data

• Supersedes: 🗺 clientLoader and clientAction #5070
• Related:
  • initial work on clientLoader & clientAction #5543
  • RFC: Static Pages / Browser Only Fetching #2853

Background

• Today Remix requires all data loading to happen on the server
• Sometimes your data source is from the browser (like `localStorage``) and you need a second paradigm for that data outside of Remix
• Sometimes you keep a local cache of server data (like indexeddb) and you need a second paradigm for that data outside of Remix
• Sometimes you want your route's data to come from a combination of both the server and the client (ie saved database user permissions and local storage UI preferences)

Proposal

Add support for clientLoader and clientAction in route module exports:

Client Loaders

Client loaders are just like React Router loaders receiving the request and params for the next location. They also have a loader function that they can call to get the data from the server. This enables a client loader to be able to return data from the server, the client, or both.

export async function clientLoader({ request, params, loader }) {
  let permissions = await loader();
  let prefs = localStorage.getItem("prefs");
  return { permissions, prefs };
}

export async function loader() {
  return db.getPermissions();
}

Behavior

client loader	loader	behavior
	✅	today's behavior, loader called on navigation
✅	✅	client loader will be called on navigation, up to the app to call loader for the server loader to be called. Original document request will call loader and the initial data will be returned from loader(), nearest suspense boundary will render for async client loaders
✅		client loaders will be called on navigation, original document request will fallback to nearest suspense boundary for async client loaders

Client Actions

Similarly to loaders, routes can export a clientAction function that will be called instead of the server action.

export function clientAction({ request, params, action }) {
  // save server-persisted preferences
  await action();

  // save local-persisted preferences
  let formData = await request.formData();
  localStorage.setItem("persistSidebar", formData.get("sidebar"));
  return { ok: true };
}

export function action({ request }) {
  return db.savePrefs(await request.formData());
}

Behavior

client action	action	behavior
	✅	Today's behavior, action called and then data is revalidated (including client loaders now)
✅	✅	Client action is called, up to the app to call the server action, all data revalidated
✅		Client action is called, calling action will throw. All data revalidated

For document POST requests (<Form reloadDocument method="post" />), the client action is completely ignored.

Benefits

Apps can now use a combination of persistent server and client data without needing to use a second paradigm outside of Remix, or skipping Remix and building client-side only with React Router.

This also creates fluid migration paths from React Router to Remix (and in the future, RSC) for in the Remix SPA proposal.

[ChristianJacobsen]

I've sorely missed a utility to solve precisely this without having to rely on useEffect directly. So a thumbs up from me!

How will awaiting the loader in the clientLoader work if you are deferring parts of the loader? Will we be able to further await some of these deferred promises in a clientLoader? And if yes, how will that function?

I can't really see a place where I would want the above-mentioned functionality, but I thought I'd mention it anyways.

[brophdawg11]

@lili21 Yes, you can return raw JSON with en embedded Promise from clientLoader and use it with Await

[lili21]

I'm bit of confused about the behavior when I have clientLoader and loader both. it looks like I have to call the loader inside clientLoader.

[sergiodxa]

@lili21 yes, your clientLoader replaces the default one and if you still want to call the server loader you need to do it manually by running the serverLoader function the clientLoader receives in its arguments. The docs for clientLoader was merged recently, you can read it here https://remix.run/docs/en/dev/route/client-loader, here https://remix.run/docs/en/dev/route/client-action and here https://remix.run/docs/en/dev/route/hydrate-fallback

[lili21]

@sergiodxa is there any alpha/next/canary version I can try it right now?

[sergiodxa]

The 2.4.0-pre I think

[brophdawg11]

This also supercedes #4950

[brophdawg11]

A lot of folks today prefer using DataFunctionArgs instead of differentiating between LoaderFunctionArgs/ActionFunctionArgs since they share the same params. Using loader/action here will be the first divergence between the two - so something to keep in mind in case we wanted to go with a more generic serverFetch for consistency:

export function clientLoader({ request, params, serverFetch }) {...}
export function clientAction({ request, params, serverFetch }) {...}

I think this just boils down to whether we want to export ClientDataFunctionArgs in addition to ClientLoaderFunctionArgs/ClientActionFunctionArgs or not.

[kentcdodds]

ClientDataFunctionArgs

Yes please

[brophdawg11]

We are going to move forward with separate serverLoader/serverAction functions here. Now that they've diverged, there won't be a ClientDataFunctionArgs and we'll be adding a deprecation warning to DataFunctionArgs

[developit]

I really, really like this design. Also makes it easy to race server+client loads/actions where warranted, or to have client loaders/actions that depend on server loader/action data.

[developit]

Suggestion: bare returns from clientLoader() should implicitly become defer() instead of json() (as is the case with existing/server loaders). This would allow fantastic patterns like the following:

export async function loader({request}) {
  return defer({
    apiKey: API_KEY,  // not a Promise (gets sent immediately)
    result: db.get('some-key'),  // a Promise (gets deferred)
  })
}

export async function clientLoader({loader}) {
  // start the server loader if it wasn't yet:
  const serverData = loader();

  // now do some client-side loading *in parallel with the server loader*:
  const cachedResult = await idb.get('some-key');

  // if we `await` the server loader data, it'll be available on first render.
  return {cachedResult, ...(await serverData)};
}

export default function MyComponent() {
  const data = useLoaderData();

  data.cachedResult; // {"some":"data from idb, loaded on the client"}

  data.apiKey;  // "API_KEY from server loader"

  data.result;  // Promise that will resolve to the result of `db.get('some-key')`

  return <Await promise={data.result}>{result => result.foo}</Await>;
}

This also provides a mechanism for clientLoader's to load things based on non-Deferred data from a server loader. Imagine the same code as above, but with this clientLoader implementation:

export async function clientLoader({loader}) {
  // load the server data (but don't wait for Deferred data!):
  const serverData = await loader();

  // use that data to do client-side loading, still in parallel with Deferred server data:
  const headers = {authorization: `Bearer ${serverData.apiKey}`};
  const user = await (await fetch('/api/user', {headers})).json();

  return {user, ...serverData};
}

[brophdawg11]

I don't know why this didn't occur to me when we first talked about this - but this will be the inherent default without any additional changes. For server-side loaders we need to serialize the response over the network so we need to know when to opt into defer. Client loaders don't need to serialize so the raw data returned is exposed through useLoaderData verbatim so you can return a promise anywhere in a naked object, even nested below the root:

export function loader() {
  return defer({ 
    lazy: new Promise(...),
  });
}

export async function clientLoader({ serverLoader }: ClientLoaderFunctionArgs) {
  let serverData = await serverLoader<typeof loader>();
  // serverData.lazy is deserialized into a Promise so you could `await` or send it though for use with <Await>

  return {
    nested: {
      lazy: serverData.lazy,
    },
  };
}

// Run this clientLoader on hydration
clientLoader.hydrate=true


export default function Component() {
  let data = useLoaderData<typeof clientLoader>();
  return (
    <>
      <React.Suspense fallback={<p>Loading...</p>}>
        <Await resolve={data.nested.lazy}>{(value) => <p>{value}</p>}</Await>
      </React.Suspense>
    </>
  );
}

[brophdawg11]

Do we want a way to distinguish initial load versus subsequent loads? We may want to use the server data for the HTML request for perf, but then make a direct API request subsequently to bypass the Remix hop in a BFF setup.

function clientLoader({ loader }) {
  // 🤔 where would this come from?
  let isInitialDocumentRequest = ???
  if (isInitialDocumentRequest) {
    return loader(); // This resolves immediately with the hydrated server data
  } else {
    return callApiDirectly()
  }
}

A module-scoped variable might work? Or you could hack somethig on window 🤢.

@developit suggested Request.mode which does seem to map perfectly, but you can't directly set mode on a client-side created Request, so we'd have to hack it:

Object.defineProperty(req, 'mode', {
  configurable: true,
  enumerable: true,
  get:() => 'navigate'
});

[ryanflorence]

I definitely want a way to distinguish between initial document load vs client load, not sure about either of these APIs for it. I like the request one but I hate modifying built-ins 😅.

[brophdawg11]

@ryanflorence Agreed on modifying built-ins. Could go with a custom header on the Request as an option too.

[brophdawg11]

For the time being, we don't think this is necessary so won't be including anything in the MVP. The majority of use cases where clientLoader is a cache already won't run on hydration. In the less-frequent use cases where a user opts-into running the clientLoader on hydration (and SSR-ing a fallback) then they can determine initial load via a module scoped variable that they toggle on the first execution.

[jrestall]

Could Link prefetch functionality be added to React Router so that clientLoader data can be prefetched and lazy routes loaded?

It would also then be very useful to receive a flag in the clientLoader that this is a prefetch so that different caching or data loading strategies can be used.

export async function clientLoader({ mode /* initial | prefetch | navigation */ }) {
  if (mode === "prefetch") {
    // TanStack Query prefetching example primes the cache
    queryClient.prefetchQuery({
      queryKey: ['todos'],
      queryFn: fetchTodos,
    });
  } else {
    // A normal or initial navigation waits for the data, but maybe it's cached!
    return await queryClient.fetchQuery({       
      queryKey: ['todos'],
      queryFn: fetchTodos, 
    });
  }
}

Related: https://tanstack.com/router/v1/docs/guide/preloading#preloading-with-data-loaders

[ryanflorence]

I kinda like that. Also related to the "is this a document vs. a client navigation". Now we have "is this a prefetch?"

[brophdawg11]

This won't be tackled as part of this client data work as we no longer need to specify a differentiator between initial/navigation requests - so a 3rd prefetch option is no longer specifically relevant here. This will likely be reconsidered in some fashion in the Remix SPA Mode Proposal. Right now, folks can do their own "prefetch cache population" in onHover listeners, etc.

[brophdawg11]

I think folks have also asked in the past for the ability to add custom headers to the fetch call. Could this open up that use-case as well? We could take some subset of RequestInit (but not all of it - don't want them touching method/body for example)

export function clientLoader({ request, params, loader }) {
  return loader({ 
    headers: { 
      'X-Custom': 'whatever'
    }
  });
}

[ryanflorence]

Oh super interesting. What does that mean for document requests?

[sergiodxa]

We could take some subset of RequestInit (but not all of it - don't want them touching method/body for example)

I would say only allow setting headers.

[sergiodxa]

But I think it would be better to allow headers in fetcher.submit or useSubmit, the same way encType can be set to application/json there, so you know that only works with JS.

[brophdawg11]

Oh super interesting. What does that mean for document requests?

Huh, yeah nothing we can do on document requests. I think it would be something only available to client-side JS initiated requests. I found the proposal for it which aligns with that use case.

[brophdawg11]

We're punting on this as part of this RFC - it's more likely to land as a call-site option as indicated in the linked proposal above.

[kentcdodds]

First thought/concern for me is content layout shift.

This API makes it easier to do user preferences that affect rendering (like theme and timezones) on the client then the server. The easier thing is what people will do. How could we discourage CLS with this API?

[kentcdodds]

Ah yes, that limitation makes sense and would solve my concern.

[brophdawg11]

yeah, I think the current plan is that when any of your SSR'd initial matches have a client loader, they are treated like an initial load of a React Router SPA and will render the fallbackElement from RouterProvider until they all resolve.

[sergiodxa]

will render the fallbackElement from RouterProvider until they all resolve

How a fallbackElement would be defined in this case? Will we need to export the fallback?

export function Fallback() {
  // fallback for document requests as the clientLoader ends
}

There's a really old proposal from @ryanflorence to add this Fallback/Pending export to allow this kind of things too. But I think we Suspense working on SSR now it should be possible to wrap the Outlet in a Suspense?

[brophdawg11]

Right now in my branch I'm doing export function Fallback from root.tsx since the fallbackElement needs to define the full <html> document and most importantly render <Scripts> so that the app can hydrate and run the clientLoaders

[brophdawg11]

This is likely going to become something you can specify more granularly at the route level though

[frandiox]

Great addition! Just a quick concern -- consider what could happen if you forget to destructure loader or action from the clientLoader/clientAction parameters:

-export async function clientLoader({ request, params, loader }) {
+export async function clientLoader({ request, params }) {
  let permissions = await loader();
  let prefs = localStorage.getItem("prefs");
  return { permissions, prefs };
}

export async function loader() {
  return db.getPermissions();
}

Unless I'm missing something, this might get server code leaked to the browser without noticing. Maybe there should be a way to detect this and fail the build? Or maybe a job for eslint?

[brophdawg11]

Good question - that is a bit of a footgun. serverFetch would solve this. But maybe serverLoader/serverAction would make sense if we kept them separate to avoid the shadowing.

[moishinetzer]

This wasn't noted in the original discussion description but this would also open up massive ease of use for native API's allowing PWA's to essentially become remix first class citizens!

[alexanderson1993]

You mention IndexedDB in the proposal, which got me thinking about local-first, state synchronization, and realtime multiplayer. A stated goal of this proposal is to have the Remix paradigm cover more use-cases. Will there be some way to update clientLoader data outside of a navigation? Such as a websocket message, BroadcastChannel, etc.?

What about revalidation? Naturally actions should revalidate all data, but I can think of situations where only clientLoaders should be reloaded. For example, some third-party package updates some IndexedDB data. Perhaps an extension to useRevalidate would give you the option of just revalidating client loaders (which would use the same server loader data they were originally called with).

[sergiodxa]

If client-loaders decide if they fetch or not the server-loader, then useRevalidator could work as usual, it will first trigger all client-loaders and inside there you could decide to fetch or not the server-loader.

What would be useful for useRevalidator is to only revalidate specific routes, so you could do it on the route that has a client-loader and reads from IDB.

[ryanflorence]

Will there be some way to update clientLoader data outside of a navigation?

clientAction can change any data you want. So call fetcher.submit(data, { action: route }) and the client action will be called. From there its up to you to call serverAction() if you want, or just write to indexdb.

[alexanderson1993]

Awesome. Looking forward to playing with these patterns.

[fredericoo]

I have so many use cases for this, where I wish I was in react router territory. please let this become a reality!

[celebro]

client loader will be called on navigation, up to the app to call loader for the server loader to be called. Original document request will call loader and the initial data will be returned from loader(), nearest suspense boundary will render for async client loaders

Do I understand this part correctly, that if clientLoader is present, route will always suspend on initial document request? Will it be possible to skip clientLoader entirely on document requests, to prevent rendering suspense boundary? I would like to be able to use clientLoader as strictly optimization on client navigation (e.g. use custom cached data) and wouldn't want to sacrifice functionality of initial documents for that.

[brophdawg11]

Yes - this will be possible. You will opt-in to execution on initial document load - but by default clientLoader will not run on initial hydration (for your mentioned optimization use-case) but then you can choose to render a fallback and run them on hydration.

[rubber-duck-software]

Could clientLoader and clientAction provide a way to handle network errors which occur when calling the server? Thinking of #7688 . It would be pretty sweet if the below just worked

export function clientAction({ action }) {
    try {
        return action()
    } catch (e) {
        if (isNetworkError(e)) {
             // handle network error here
        } else {
            throw e
        }
    }
}

[brophdawg11]

Yep! You now get to catch those and choose to surface them as errors or not 👍

[lili21]

what's the story of error handling? is it the same of loader and action?

[lili21]

will it fallback to ErrorBoundary module?

[alexanderson1993]

Yep, any uncaught errors in loaders and actions will trigger the nearest route's error boundary - just the same as server loader and action.

[okalil]

I have a question: How can we have a "typesafe" useLoaderData() in cases where the loader is only executed on initial loading, and the clientLoader is only executed on client-side navigations?

I imagine something like:

export const loader = /* ... */

// client data is forced to match loader data type
export const clientLoader: ClientDataFunction<typeof loader> = async ({ serverLoader }) => {
   if(initialLoading) {
    const data = await serverLoader(); // inferred loader data type
    return data
    }
   return dataLoadedClientSide()
}

useLoaderData<typeof clientLoader>()

[sergiodxa]

I asked the team before, your clientLoader should return the same shape of data as the server loader, so you can just use useLoaderData<typeof loader>() and it would work because if the return returns an object with some key being a string that will also be true on the clientLoader.

If the clientLoader returns different data you will need to run the clientLoader on hydration and then use useLoaderData<typeof clientLoader>()

[AndreSilva1993]

Sorry for reviving this thread but following what you said @sergiodxa, wouldn't using the useLoaderData<typeof clientLoader>() when the data that clientLoader differs from the loader one (let's say we augment it with information only accessible on the client-side, like localStorage) mean that the types would technically be incorrect for the initial document load on SSR?

Since we would be augmenting what comes from the loader, but using const loaderData = useLoaderData<typeof clientLoader>(), the loaderData variable types would contain the augmented data which is not 100% the case given the SSR. Wouldn't something like useLoaderData<typeof loader | typeof clientLoader>() be more correct?

[sergiodxa]

If you add clientLoader.hydrate = true then your HydrateFallback component will be rendered server-side, so you will never get only the server loader data.

If you don't, you will only get clientLoader response for a client-side navigation, and in that case your UI will need to handle the missing keys anyway, so you'll probably return those client-only keys as null from the server and handle the possible null value.

export async function loader() {
  let data = await queryDataFromDatabase();
  return json({
    ...data,
    key: null,
  });
}

export async function clientLoader({ serverLoader }) {
  let serverData = await serverLoader();
  return {
    ...serverData,
    key: localStorage.getItem("key") as string | null; // overwrite null in serverData.key
  };
}

export default function Component() {
  let loaderData = useLoaderData<typeof clientLoader>()
  // use `loaderData.key` here that it's nullable
}

[AndreSilva1993]

My question was that you can in fact have a clientLoader that augments what data the server provides but not necessarily use the HydrateFallback if we don't want to hold off displaying the entire route - like the example you provided.

So yeah, agree that in those cases is probably preferred to be explicit and have the server loader return what the client loader will augment with null and also type the clientLoader return so that the components are properly typed.

[lili21]

we can do similar stuff like PPR with this. Put all static data in loader, and all dynamic data in clientLoader, and we can pre-render the static part,

[sergiodxa]

@lili21 if it's static data, why do you need it from the loader? Why not move it directly to the React components?

[lili21]

Not exactly static, like some data from CMS that won't change frequently. and for dynamic data, I mean personal data, which can't be cached.

[brophdawg11]

I would be wary of moving too much of your primary data to clientLoader as that will have potential negative impacts on SEO, performance, and introduce CLS. Client Data is an escape hatch more than a primary recommended method of loading data.

[eglove]

oh wow, I was thinking about this a lot recently. Why is browser storage a second-class citizen that requires escape hatches like useEffect? I love this!

[dcramer]

About to dig into the source, but immediate hurdle I'm hitting is not having access to global context. We're forced to use a root level loader to pass in various levels of config (e.g. a cookie header). That's fine, but I don't seem to have any way to take that root loader context and pass it into child clientLoader's. This is the same rough prroblem that exists today with the top level ErrorBoundary as well.

[dcramer]

I do see a context arg, but its undefined, and I'm not sure if thats just a type error or something thats expected to be usable or future usable.

[ryanflorence]

the context should only be for the loader, not clientLoader, that's a server thing.

Can you use document.cookie in clientLoader and request.headers.get('cookie') in loader?

[ryanflorence]

but I don't seem to have any way to take that root loader context and pass it into child clientLoader's

As high up as needed (root.tsx?) I'd return whatever config your client loaders need and then dump them into window.CONFIG_FROM_SERVER or localStorage, then your clientLoaders just access them from there. You're not on a server so window and localStorage are a mutable context you can use.

[brophdawg11]

There's a proposal for client-side context: remix-run/react-router#9856

I'd like to see it implemented to keep the APIs closer together 😉

[dcramer]

Begrudgingly made window.REMIX_CONTEXT for now. Def works and I've managed to create isomorphic loaders using this pattern.

[dcramer]

Another issue I've hit, the need for more isomorphic utilities. For example, the json() bit is solvable in clientLoader vs loader (albeit kind of silly to force differentiation), but what about things like a redirect? Example common use case would be user sessions. They're hitting a route which requires auth. I want to avoid the server hop entirely, and send them to the login route on the cilent side when auth isnt present.

[brophdawg11]

You can still return a redirect Response from a clientLoader (either raw or via the redirect utility) - just as you would from a server loader.

You can also return json if you want - it just puts you through an unnecessary serialization/deserialization step.

[dcramer]

TS ruined me here with automatic imports - realized there's two common json exports that work on loaders: remix-run/node, and remix-run/server-runtime. Only the latter works in this case, and guessing the same for the redirect utility.

[brophdawg11]

Interesting - they're the same thing at the end of the day (@remix-run/node re-exports the function from @remix-run/server-runtime) but I wonder if importing from node in client code is causing an issue at bundle time...I'll see if I can dig in a bit today

[brophdawg11]

Looks like something in the compiler strips them when. coming from the node package. We're going to re-export from the react package to avoid this: #8351

[p-christ]

If a root has a server loader and a client loader with hydrate set to true, will navigation to the root be instant or will the navigation wait for the server loader to respond?

(Assuming the client loader doesn't await the server loader, it just passes along the deferred server loader result as a promise)

[brophdawg11]

Without a HydrateFallback, the route will server render the component with the server loader data, so upon initial document load you'll see the rendered content.

If you set clientLoader.hydrate=true, then it will run the clientLoader on hydration and will update the server-rendered UI by re-rendering the component with the clientLoader data.