Announcing SWR 1.0

Almost 2 years ago we open sourced SWR, the tiny data-fetching React library that people love. Today we are reaching another milestone: the 1.0 version of SWR!

What’s New

Smaller Size

Performance is one of the most important features of SWR. In 1.0, we made the library significantly smaller without removing any existing features:

• 41% smaller core (24% smaller when gzipped, 3.9 kB)
• 52% smaller package install size
• Improved tree-shaking

There are many reasons to make the library lightweight: your application will have a smaller bundle, a leaner runtime, and a smaller node_modules directory.

We’ve also improved the bundling of the package, and it now supports path imports:

import useSWR from 'swr'
import useSWRInfinite from 'swr/infinite'

If you are not using useSWRInfinite, it will not be included in your application.

Fallback Data

In 1.0, there’s a new fallback option that you can provide any pre-fetched data as the initial value of all SWR hooks with specific keys:

<SWRConfig value={{
  fallback: {
    '/api/user': { name: 'Bob', ... },
    '/api/items': ...,
    ...
  }
}}>
  <App/>
</SWRConfig>

This is very helpful for scenarios such as SSG, SSR, and data mockup for testing. Check the docs Next.js SSG and SSR for more details.

For better consistency and to avoid confusion, the old initialData is now renamed to fallbackData, which still provides a single fallback value for the given hook.

Immutable Mode

Sometimes you want to mark a resource as immutable if it will never change. It’s better to disable automatic revalidations for it and only make the request once. There is now a helper hook to make this easier:

import useSWRImmutable from 'swr/immutable'
 
// ...
 
useSWRImmutable(key, fetcher, options)

It has the exact same API as the useSWR hook, but it will never revalidate upon tab focus or network recovery. There’s also a new option, revalidateIfStale, you can use to control the behavior precisely. More information can be found here.

Custom Cache Provider

By default, SWR uses a single global cache to store all the data. In 1.0, you are able to customize it with the new provider option:

<SWRConfig
  value={{
    provider: () => myCache
  }}
>
  <App />
</SWRConfig>

You can use this new feature to do many powerful things. We have a couple of examples here: Mutate Multiple Keys with RegEx, LocalStorage Based Persistent Cache, Reset Cache Between Tests.

This new cache provider API is also more compatible with concurrent rendering of React 18. If you are adding a cache provider, make sure to use the global mutate function returned from useSWRConfig().

You can read the docs Cache Provider for more details.

useSWRConfig()

There is a new Hook API to return all global configurations, including the current cache provider and global mutate function:

import { useSWRConfig } from 'swr'
 
function Foo() {
  const { refreshInterval, cache, mutate, ...restConfig } = useSWRConfig()
 
  // ...
}

More information can be found here.

Middleware

SWR Middlewares provide a new way for you to build and reuse abstractions on top of SWR hooks:

<SWRConfig value={{ use: [...middleware] }}>
 
// ... or directly in `useSWR`:
useSWR(key, fetcher, { use: [...middleware] })

A lot of new ideas can be implemented with this feature, and we’ve built some examples: Request Logger, Keep Previous Data When Changing the Key, and Serialize Object Keys.

Check the Middleware API for more details.

Improvements and Better Test Coverage

Since 0.x, we’ve made hundreds of small improvements and bugfixes. SWR now has 157 tests that cover most of the edge cases in data fetching. Read the Changelog for more details.

Docs Translations

Thanks to our contributors and Nextra’s i18n feature, we now offer SWR documentation in six different languages:

• English
• Spanish
• Simplified Chinese
• Japanese
• Korean
• Russian

Migration Guide

Update useSWRInfinite Imports

useSWRInfinite needs to be imported from swr/infinite:

- import { useSWRInfinite } from 'swr'
+ import useSWRInfinite from 'swr/infinite'

If you are using the corresponding types, update the import path too:

- import { SWRInfiniteConfiguration, SWRInfiniteResponse } from 'swr'
+ import { SWRInfiniteConfiguration, SWRInfiniteResponse } from 'swr/infinite'

Change revalidate to mutate

useSWR no longer returns the revalidate method, change to mutate instead:

- const { revalidate } = useSWR(key, fetcher, options)
+ const { mutate } = useSWR(key, fetcher, options)
 
 
  // ...
 
 
- revalidate()
+ mutate()

Rename initialData to fallbackData

- useSWR(key, fetcher, { initialData: ... })
+ useSWR(key, fetcher, { fallbackData: ... })

No More Default Fetcher

SWR no longer provides the default fetcher (a fetch call that parses the data as JSON). The easiest way to migrate the change is to use the <SWRConfig> component:

;<SWRConfig value={{ fetcher: url => fetch(url).then(res => res.json()) }}>
  <App />
</SWRConfig>
 
// ... or
useSWR(key, url => fetch(url).then(res => res.json()))

Recommend to Use the Hook-Returned mutate

This is not a breaking change, but we will now recommend to always use the mutate returned from the useSWRConfig hook:

- import { mutate } from 'swr'
+ import { useSWRConfig } from 'swr'
 
 
  function Foo () {
+   const { mutate } = useSWRConfig()
 
    return <button onClick={() => mutate('key')}>
      Mutate Key
    </button>
  }

If you are not using a cache provider, the current global import import { mutate } from 'swr' still works.

Renamed Types

If you are using TypeScript, the following type names have been changed for consistency:

Beta and Unofficial Feature Users

If you are using a beta version of SWR, or using any undocumented APIs, please be aware of the following changes:

• import { cache } from 'swr' is removed; use the new useSWRConfig API instead.
• import { createCache } from 'swr' is removed; use the new Cache Provider API instead.
• revalidateWhenStale is renamed to revalidateIfStale.
• middlewares is renamed to use.

Changelog

Read the full Changelog on GitHub.

What’s Next

In future releases, we will keep improving the library while maintaining the stability. We are also aiming to embrace future React versions, as several new features and improvements in 1.0 are already preparing for that. In addition, we are also working on new features to improve the experience of doing data fetching in React and the experience of using this library.

If you have any feedback about this release, please let us know.

Thank You!

Special thanks to Toru Kobayashi and Yixuan Xu for their contributions to the library, and Paco Coursey, uttk, Tomohiro SHIOYA, Markoz Peña, SeulGi Choi, Fang Lu, Valentin Politov for their work on the translations and docs. This release can’t happen without them.

We also want to thank the entire community, our 110 contributors (+ 45 docs contributors), and everyone who helped and gave us feedback!