Introducing the new Next.js and SWR clients
Join our Open Source Community!
Join our Discord community to explore the exciting world of Backend for Frontend (BFF) architecture! We're a group of web development enthusiasts who are passionate about creating scalable and efficient APIs that power modern web and mobile apps.
Our first Next.js client took a lot of inspiration from SWR, but we choose to build our own fetching library because SWR was lacking a couple of important features that we needed. Most notably built-in support for authentication, mutations (SWR is focused on fetching data, not updating it) and better SSR functionality. This suited us well at first, but along the way we realised that we had to build and maintain a lot of the same features that SWR already had. Why solve a problem that has already been solved?.
We started experimenting with using our TypeScript client together with SWR while building our cloud alpha. This turned out to be a great match, our TypeScript client is using fetch for making requests to the WunderGraph API, which is serving GraphQL operations over a JSON RPC style API and allows us to benefit from techniques like
stale-while-revalidate. Which is exactly what SWR stands for.
Quickly after that we released our official integration with SWR, so we could start testing with the community. This was well received and it greatly improved the developer experience for our users. It gave us extra features like optimistic updates, invalidating queries, middleware support (more on this later) and it drastically reduced the amount of complexity in our code. This gave us the confidence to make SWR our default data fetching library for React and with the release of SWR 2.0RC it was time to rewrite our Next.js client to use SWR.
Now let's dive into the details of the new Next.js client. See what's changed and how you can use the new features.
This post applies to:
We tried to keep the new API similar to the previous, but there are some notable (breaking) changes.
The generated Next.js client no longer creates individual hooks for every operation, but instead we simply have 3 hooks,
useMutation that are fully typed. This makes the code very lightweight in production bundles while still benefiting from the full power of TypeScript.
You can now write:
Conditionally fetching data is now also possible:
refetch has been renamed to
mutate to be inline with the SWR API. Calling
mutate() will invalidate the cache and refetch the query, you can also pass data to
mutate to update the cache without refetching, this is useful for optimistic updates for example.
There is no
useLiveQuery hook anymore, this is now just
useQuery with the
liveQuery option set to
true, allowing you to easily turn every query into a live query.
Subscriptions have a similar API. Nothing significant has changed here, but you can now check if a subscription is being setup or is active with the
Mutations are also very similar to the previous API.
mutate has been renamed to
trigger to prevent confusion with the
mutate function from SWR.
What's great about the new API is that it's now easier to invalidate queries after a mutation.
Let's say we have a query that fetches the current user's profile in one component and we have a form that updates the profile. We can add an
onSuccess handler to the mutation that calls
mutate (invalidate) on the
Now we could even make this fully optimistic by mutating the
GetProfile cache instead and then refetching it, it would look something like this:
The new client also supports SSR and even works with live queries and subscriptions.
Simply wrap your
withWunderGraph and you're good to go.
So how does this work?
Just like the old client we use
react-ssr-prepass to render the component tree on the server inside
getInitialProps and collect all fetch promises from the
useSubscription hooks and wait for them to resolve. This is then passed to the client, which is then passed to the
SWRConfig fallback option . This is all done automatically, you don't have to do anything.
As I explained in the introduction, SWR supports middlware , which is a really powerful feature and allows you to add functionality to individual hooks or globally using
SWRConfig. The Next.js package uses middleware to add support for SSR to the hooks. Let's go a bit into to details how this works.
Our SSR middleware is added to
SWRConfig internally by
withWunderGraph, I'll go over the code here to explain how it works.
This is how the logic works. First we check if this hook is being called on the server, if SSR is enabled and if it is a WunderGraph operation. If not we just return the swr hook.
Now we serialize the key that we need for the ssrCache and to pass it down to the SWR
fallback. We check if this is an authenticated operation, if the user isn't logged in we don't need to execute the operation for SSR.
LiveQueries and subscriptions don't have a fetcher because data is loaded async, but for SSR we create a fetcher that will call the query with
subscribeOnce set to true. This will return the subscription data directly instead of setting up an event stream, so we can server side render subscriptions ❤️.
Now we set the fetcher to our ssrCache with the serialized key. Which is then read in
getInitialProps, returned to the client and passed to the
fallback option of
SWRConfig and SWR + Next.js do the rest.
So that's it, we are now using SWR as our default data fetching library, giving you all the benefits, like optimistic updates while consuming WunderGraph APIs. It already improved our internal developer experience a lot and we are excited to hear about your experience with the new clients.
We're also interested in your experience about this topic in general.
- Are you using SWR? What do you think about it? What are your favorite features?
- Do you use other libraries for data fetching and cache management, like React Query? (hint; we will release a React Query integration soon).
Share it in the comments below or come join us on our Discord server .
WunderGraph Cloud Early Access
Are you ready for the next generation of
Serverless Infraless API Development? Join the waitlist for WunderGraph Cloud Early Access and be the first to try it out.