Usage with Next.js

App Router

Server Components

In Next.js App Router, all components are React Server Components (RSC) by default. You can import SWRConfig and the key serialization APIs from SWR in RSC.

import { unstable_serialize } from 'swr' // ✅ Available in server components
import { unstable_serialize as infinite_unstable_serialize } from 'swr/infinite' // ✅ Available in server components

import { SWRConfig } from 'swr' // ✅ Available in server components
import { preload } from 'swr' // ✅ Disponible dans les Server Components

You could not import hook APIs from SWR since they are not available in RSC.

import useSWR from 'swr' // ❌ This is not available in server components
import useSWRInfinite from 'swr/infinite' // ❌ This is not available in server components
import useSWRMutation from 'swr/mutation' // ❌ This is not available in server components

Client Components

You can mark your components with 'use client' directive or import SWR from client components, both ways will allow you to use the SWR client data fetching hooks.

'use client'

import useSWR from 'swr'

export default function Page() {
  const { data } = useSWR('/api/user', fetcher)
  return <h1>{data.name}</h1>
}

Prefetch Data in Server Components

L'approche recommandée dans les React Server Components (RSC) consiste à lancer la récupération avec preload, puis à transmettre les données renvoyées à l'arbre des composants clients via l'option cacheData de <SWRConfig> :

import { preload, SWRConfig } from 'swr'

export default async function Layout({ children }: { children: React.ReactNode }) {
  const cacheData = {
    ...preload('/api/user', fetchUserFromAPI),
    ...preload('/api/posts', fetchPostsFromAPI),
  }

  return (
    <SWRConfig value={{ cacheData }}>
      {children}
    </SWRConfig>
  )
}

Les deux appels à preload lancent immédiatement la récupération des données. Les requêtes s'exécutent donc en parallèle sans être attendues dans le layout.

Dans les React Server Components, les promesses contenues dans cacheData peuvent traverser la frontière "use client", et SWR les résout automatiquement pendant le rendu côté serveur :

'use client'

import useSWR from 'swr'

export default function Page() {
  // SWR résout les données préchargées par le Server Component.
  // Both `user` and `posts` are ready during SSR and client hydration.
  const { data: user } = useSWR('/api/user', fetcher)
  const { data: posts } = useSWR('/api/posts', fetcher)

  return (
    <div>
      <h1>{user.name}'s Posts</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  )
}

SWR utilise le résultat chargé sur le serveur pour le rendu initial. Côté client, il prend ensuite le relais et conserve son comportement habituel de revalidation.

Avec preload et cacheData, la récupération commence le plus tôt possible sur le serveur. Seules les frontières d'interface qui consomment les données, comme la frontière Suspense la plus proche ou le layout Next.js, sont bloquées pendant le streaming SSR.

Pour adopter progressivement ce modèle de préchargement dans votre application, vous pouvez activer l'option strictServerPrefetchWarning. Cela affichera un message d'avertissement dans la console lorsqu'une clé n'a pas de données pré-remplies fournies, vous aidant à identifier quels appels de récupération de données pourraient bénéficier d'un préchargement côté serveur.

Fonctionnement de `cacheData`

Cette fonctionnalité nécessite SWR 2.5.0-beta.1 ou une version ultérieure et reste expérimentale.

Dans un Server Component, preload(key, fetcher) lance immédiatement la récupération des données et renvoie un objet CacheData limité à la requête. Transmettez cet objet à l'option cacheData de SWRConfig :

import { preload, SWRConfig } from 'swr'
import { User } from './user'

const getUser = () => fetchUserFromDatabase()

export default function Page() {
  const cacheData = preload('/api/user', getUser)

  return (
    <SWRConfig value={{ cacheData }}>
      <User />
    </SWRConfig>
  )
}

Le composant client utilise la même clé avec son fetcher côté client habituel :

'use client'

import useSWR from 'swr'

const fetcher = (url: string) => fetch(url).then(res => res.json())

export function User() {
  const { data } = useSWR('/api/user', fetcher)
  return <h1>{data?.name}</h1>
}

SWR utilise le résultat chargé sur le serveur pour le rendu initial, l'écrit dans le cache client pendant l'hydratation et évite une requête initiale en double côté client. Les revalidations suivantes utilisent toujours le fetcher côté client.

Chaque appel à preload renvoie un nouvel objet. Fusionnez ces objets pour précharger plusieurs clés sans les attendre :

const cacheData = {
  ...preload('/api/user', getUser),
  ...preload('/api/posts', getPosts),
}

preload sérialise automatiquement les clés SWR complexes. L'option cacheData est uniquement prise en charge par SWRConfig ; elle ne peut pas être transmise directement à useSWR.

Client Side Data Fetching

If your page contains frequently updating data, and you don’t need to pre-render the data, SWR is a perfect fit and no special setup needed: just import useSWR and use the hook inside any components that use the data.

Here’s how it works:

First, immediately show the page without data. You can show loading states for missing data.
Then, fetch the data on the client side and display it when ready.

This approach works well for user dashboard pages, for example. Because a dashboard is a private, user-specific page, SEO is not relevant and the page doesn’t need to be pre-rendered. The data is frequently updated, which requires request-time data fetching.

Pre-rendering with Default Data

If the page must be pre-rendered, Next.js supports 2 forms of pre-rendering: Static Generation (SSG) and Server-side Rendering (SSR).

Together with SWR, you can pre-render the page for SEO, and also have features such as caching, revalidation, focus tracking, refetching on interval on the client side.

Vous pouvez utiliser l'option cacheData de SWRConfig pour placer les données récupérées sur le serveur dans le cache de tous les hooks SWR de cette frontière.

For example with getStaticProps:

 export async function getStaticProps () {
  // `getStaticProps` is executed on the server side.
  const article = await getArticleFromAPI()
  return {
    props: {
      cacheData: {
        '/api/article': article
      }
    }
  }
}

function Article() {
  // `data` est disponible grâce à `cacheData`, fourni par le serveur.
  const { data } = useSWR('/api/article', fetcher)
  return <h1>{data.title}</h1>
}

export default function Page({ cacheData }) {
  // SWR hooks inside the `SWRConfig` boundary will use those values.
  return (
    <SWRConfig value={{ cacheData }}>
      <Article />
    </SWRConfig>
  )
}

The page is still pre-rendered. It's SEO friendly, fast to response, but also fully powered by SWR on the client side. The data can be dynamic and self-updated over time.

Le composant Article affiche les données prégénérées et les hydrate dans le cache client sans requête initiale en double. Les événements de revalidation ultérieurs utilisent toujours le fetcher client.

Complex Keys

useSWR accepte des clés de type array et function. Lorsque vous créez cacheData manuellement, sérialisez ces clés avec unstable_serialize.

import useSWR, { unstable_serialize } from 'swr'

export async function getStaticProps () {
  const article = await getArticleFromAPI(1)
  return {
    props: {
      cacheData: {
        // unstable_serialize() array style key
        [unstable_serialize(['api', 'article', 1])]: article,
      }
    }
  }
}

function Article() {
  // using an array style key.
  const { data } = useSWR(['api', 'article', 1], fetcher)
  return <h1>{data.title}</h1>
}

export default function Page({ cacheData }) {
  return (
    <SWRConfig value={{ cacheData }}>
      <Article />
    </SWRConfig>
  )
}

Usage with Next.js

On this page