What approach would you prefer for our client-side caching?

[ismay]

We're researching how to implement client-side caching for our ecosystem (jira issue here: https://jira.dhis2.org/browse/LIBS-166). I've taken a look at a couple of libraries, with react-query and swr in particular. I've implemented them in the app-runtime in a rudimentary fashion, with tests to demonstrate the functionality. I've also added react-query directly to an app, using the data-engine as a fetcher, to test what that approach would be like. PRs below:

• feat(runtime): cache queries with react query app-runtime#824 (react-query)
• feat(runtime): cache queries with useSWR app-runtime#828 (use-swr)
• feat: use react-query directly scheduler-app#183 (using react-query directly with the engine as a fetcher)

If you're interested, I've left notes on what stood out to me about each approach. The purpose of this discussion is to form an initial opinion on what we all prefer, and why. I recommend going through each PR, linked docs and the notes to get an idea of each approach.

After that, we should have more of an idea of our needs, concerns, etc. I was thinking as a follow up we could then investigate further, see if any concerns/needs can be addressed. After that a meeting to decide which approach to go with and then the final implementation.

To structure the discussion a bit, I've suggested each approach as an answer to the main discussion question: What approach would you prefer for our client-side caching?

• Please upvote the approach you prefer (make sure to use the upvote on the left, not thumbs up, so that we all use the same approach)
• Please comment with the pros you see for each approach as a comment to each answer (I was thinking just pros would be simpler than pros/cons. After all one libs con is the other lib's pro).
• If you feel a fundamentally different approach is missing (for example you think a completely different lib would be better) feel free to post that as an answer and list the pros you see in a comment to that answer.

[ismay]

react-query used internally in the app-runtime: dhis2/app-runtime#824

[ismay]

Pros:

• The cache key for a group of queries will change if a single query of the group of queries changes, even though it should only affect the cache key of the changed query. This means that currently caching isn't as efficient with multiple queries for one hook. This affects both swr and react-query, however, react-query's useQueries does allow passing multiple queries and caching them separately. Would introduce extra complexity, but I think it would allow us to cache multiple resource queries efficiently without any user facing changes. It doesn't seem like that would be possible with swr.
• The deterministic cache key serialization seems like less of a footgun than swr shallow equality check. Unlike with swr's cache key, react-query's cache key should not be adversely affected if you accidentally pass a new object each render, or mutate an object used for the cache key.
• Currently this approach does not cancel requests, as per react-query's recommendations. However, unlike swr, react-query does provide an explicit API for request cancellation, so if we do want it, it should be easier to implement.
• React-query comes with a refetch function that returns a promise, just like our own refetch. SWR does not provide a refetch. I suspect it would be more complex to not break our refetch API with swr, whereas with react-query if we don't want to break the refetch API we're basically there.
• As it currently stands, I think it would be possible to implement react-query without any user facing breaking changes in the app-runtime API.
• From working with it, react-query has good documentation in my opinion. It also seems very feature complete. Everything I could think of had already been implemented. Whereas with swr a couple of things were still open issues, or I had to resort to checking the source to find out if something worked. So it seems ahead of swr in terms of features and docs.
• I personally found react-query's more explicit API easier to work with than swr. It might not look as slick, but I care more about the maintainability, which I feel is better with react-query.

[ismay]

For more info on the pros of react-query from the perspective of the author: he has written some points on the differences between react-query and swr here: https://blog.logrocket.com/caching-clash-useswr-vs-react-query/#comment-1447 (see also the comments below). He's also written an elaborate comparison here that seems quite transparent: https://react-query.tanstack.com/comparison

[ismay]

swr used internally in the app-runtime: dhis2/app-runtime#828

[ismay]

Pros:

• There is probably a performance benefit to swr's cache key invalidation mechanism, as swr does referential equality checks, compared to react-query's serializing and comparing. Though I haven't measured it, so I'm assuming for now. The difference would be the speed at which a query key can be serialized and compared, vs a shallow compare of two query keys.
• Medi mentioned that there's a difference in the bundle size for swr: https://bundlephobia.com/[email protected] and react-query: https://bundlephobia.com/[email protected]. I should note that react-query does a fair amount more, so this comparison doesn't compare the size when controlled for similar functionality. If we want to know the details we should check the impact on bundle size using for example the two app-runtime PRs, which have quite similar functionality.

[ismay]

react-query used in an app directly, with the app-runtime's data-engine as a fetcher: dhis2/scheduler-app#183

[ismay]

Pros:

• This way we're not duplicating react-query's implementation by having our own hook that under the hood calls react-query (which has a very similar API as well). Instead we're just using react-query directly. That means we can rely on their ecosystem, their features, documentation, tests and maintenance, instead of having to do this ourselves, or filter it through our API. This is the biggest benefit to me, I feel in the long run it would save us a lot of maintenance time without sacrificing the platform specific overrides, which could reside in the fetcher function.
• This way we won't have to solve the issue of caching multiple queries correctly, as we can just use react-query's useQueries directly.
• There's a ton of other functionality that we could then also just use immediately, instead of having to filter it through our existing API (which I think will become increasingly difficult as our ecosystem matures and the number of features we want to support increases), like dependent queries, invalidating queries manually, optimistic updates, scroll restoration, etc.
• The provider and the default fetcher could be provided by the app-shell, which means that a user would have a very similar experience to our own useDataQuery hook.
• Our engine is already suited as a fetcher function for react-query. I can imagine we'd want to make adjustments, but generally it already works as is.
• This could be adopted incrementally, as changes to the app-runtime wouldn't be necessary for this approach.

[mediremi]

Personally I like this approach (combined with providing a default queryFn through the app adapter) the most since it seems to be the simplest to implement and we can adopt incrementally.

[varl]

Cons:

• Does not align as well with the conceptual goals of the App Platform.
• External developers will have to absorb the complexity of using SWR/react-query directly in their apps instead of us absorbing the complexity in one place and everyone else benefiting from our efforts.
• Easy now, hard later. Adoption is easy, maintenance over time throughout our suite of applications is not. Adoption for us is easy, for 3rd party devs it may not be.

[ismay]

External developers will have to absorb the complexity of using SWR/react-query directly in their apps instead of us absorbing the complexity in one place and everyone else benefiting from our efforts.

To me there are different areas of complexity. I find the way the app-platform smooths over api inconsistencies nice for example (but that could be contained in a fetcher function). Now, react-query has a lot more activity than our lib, so I've found it easier to find docs, examples, etc. there.

Our own hook isn't very different from using react-query directly, so I'd argue that the complexity isn't increased by using react-query directly (or reduced by using our hook). Besides that, I found it easier to use react-query directly as there's not an extra layer of abstraction in between you and it, and if you have problems you're sharing them with a huge community, which makes them a lot easier to debug.

We're a small team, so I don't think our efforts will be able to compete with react-query for creating what is essentially the same functionality. So I'd argue that we're increasing complexity for the user, not reducing.

Easy now, hard later. Adoption is easy, maintenance over time throughout our suite of applications is not. Adoption for us is easy, for 3rd party devs it may not be.

I think we have the same goals, but in my experience it has been easier/better to use an established open source lib over rolling my own. We've talked about this before though, and as you mentioned it's one of the big topics in this discussion. I wonder what the best way would be to resolve this discussion?

[HendrikThePendric]

I gave a thumbs-up to the internal solution using react-query. It seems that react-query fits a bit better with our existing API than swr. The solution which uses react-query directly seems interesting as well, but I think a solution where we use it internally will be a bit more flexible/future-proof.

I noticed react-query also has a useMutation hook. I suppose caching is not very relevant for mutations, so there is no real need to make any changes to our useDataMutation hook. On the other hand, it might be beneficial to use that internally as well. What are your recommendation with regards to this @ismay?

[ismay]

The solution which uses react-query directly seems interesting as well, but I think a solution where we use it internally will be a bit more flexible/future-proof.

Could you elaborate on this? To me the opposite seems true. Using react-query directly seems like the more flexible/future-proof solution to me as it doesn't add an additional layer and it still allows for platform specific overrides through the fetcher function. The upside I personally see to sticking with the app-platform wrapper is that at this point in time it will allow us to upgrade with less user-facing changes. However, I suspect we will see greater costs in the future for this approach as we're maintaining a wrapper that offers similar functionality to react-query (assuming the platform specific overrides could be encapsulated in the fetcher function), but which has to be maintained by us. Any expansion of functionality would have to be filtered through our api, which will become increasingly difficult. And we're already strapped for time. Delaying the move to react-query to the future could mean that the migration would be more costly than it is now.

I noticed react-query also has a useMutation hook. I suppose caching is not very relevant for mutations, so there is no real need to make any changes to our useDataMutation hook. On the other hand, it might be beneficial to use that internally as well.

See here: https://react-query.tanstack.com/guides/mutations#mutation-side-effects. Since react-query can be seen as a library that provides a solution for everything query-related they provide this for hooking into react-query as well. Which means you can do things like optimistic updates, query invalidation, automatic refetches, etc.

[HendrikThePendric]

To elaborate:

• With flexible I mean that if we use react-query directly we will always be limited to what they decide to implement and how they choose to.
• With future proof I pretty much mean the same thing: we know that reducing network traffic is an important point for our users and thus for our platform. Perhaps client side caching is something we are going to focus on a lot, and we come up with some complex DHIS2 specific solution. For me it's hard to predict whether just overriding the fetcher function is going to enable us to implement this solution. However, if we wrapped the tool, I know we're going to be OK, because we can do whatever we want.

[varl]

We are missing one point of comparison here, and that is SWR implemented directly in an app with the DataEngine as a fetcher.

Without it, I don't think react-query directly in an app is qualified as an option, unless SWR-in-app was left out for a reason?

[ismay]

Yeah, I mostly left it out because the implementation would be fairly similar. I considered the direct usage of either swr or react-query in an app to be the main talking point of that suggestion. I considered the specific library we use to do that to be more of a detail.

[ismay]

If you feel it would be something worth having I can create a PR for that as well. Let me know!