feat: add preload function

[koba04]

This is an experimental implementation to preload fetcher functions. The following is an example.

import useSWR, { preload } from 'swr'

// before rendering
preload('/api/user', fetcher);

const Page = () => {
  const { data } = useSWR('/api/user', fetcher);
  return <div>...</div>
}

The preload function is necessary to avoid waterfall problems with the suspense mode.
Currently, this is implemented as middleware, but the API might be changed before merging.

The limitation of the current implementation is that we have to use useSWR from swr/preload.
This is added as a built-in middleware

The following has the waterfall problem.

import useSWR, { preload } from 'swr'

const Page = () => {
  // this suspends the first rendering
  const { data: user } = useSWR('/api/user', fetcher, { suspense: true });
  // this start fetching only after `/api/user` has been fetched
  const { data: movies } = useSWR('/api/movies', fetcher, { suspense: true });
  return <div>...</div>
}

To avoid that, we should preload fetcher functions. preload is the function for it.

import useSWR, { preload } from 'swr'

// before rendering
preload('/api/user', fetcher);
preload('/api/movies', fetcher);

const Page = () => {
  // These fetcher functions have been already fetched by calling `prefetch`.
  const { data: user } = useSWR('/api/user', fetcher, { suspense: true });
  const { data: movies } = useSWR('/api/movies', fetcher, { suspense: true });
  return <div>...</div>
}

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 85f160c:

Sandbox	Source
SWR-Basic	Configuration
SWR-States	Configuration
SWR-Infinite	Configuration
SWR-SSR	Configuration

[shuding]

I think we can try building this into the default useSWR hook (import useSWR from 'swr'), maybe make it a default middleware that is always included here: https://github.com/vercel/swr/blob/main/_internal/utils/resolve-args.ts#L19-L25

[koba04]

@shuding Thank you! That makes sense, I'll try it 👍

[koba04]

I've renamed the API from prefetch to preload.

[koba04]

If this becomes an async function, the following test is failed.

swr/test/use-swr-error.test.tsx

Line 433 in 9263ca7

it('should reset isValidating when an error occured synchronously', async () => {

[shuding]

Makes sense!

[koba04]

I've added a test for resetting an error when preloading has been failed.

[huozhi]

should this be bound with cache in global state?

[koba04]

@huozhi Thank you! That makes sense to me.
But does the preload function have to accept cache as the argument to use the global state? (It might work if we always use a global cache to store the value)

// we need the cache argument to get REQUEST from SWRGlobalState
preload(key, fetcher, cache) 

[shuding]

I think it's OK to make it always global and apply to any cache layers for now (just like fallback) considering the major use cases of preload. If necessary we can add an optional cache parameter in the future, that wouldn't be breaking.

[koba04]

I've used SWRGlobalState to store preloading requests.
85f160c

[amanmahajan7]

Thanks for this API. I wanted to confirm, does it use custom cache if provider config is set?

[huozhi]

Looks good on my side

[shuding]

Looks amazing, thank you!

[koba04]

Thank you!

[zelal-dev]

Great..!! It looks amazing, best wishes!