Anunciando SWR v1.0

Quase 2 anos atrás nós liberamos o SWR em código aberto (opens in a new tab), a pequena biblioteca React de data fetching que as pessoas adoram. Hoje estamos atingindo mais um marco: a versão 1.0 do SWR!

O que há de novo

Tamanho Menor

Desempenho é um dos recursos mais importantes do SWR. Na versão 1.0, tornamos a biblioteca significativamente menor sem remover nenhum recurso existente:

• Core 41% menor (24% menor quando compactado, 3,9 kB)
• Tamanho de instalação do pacote 52% menor
• Tree-shaking melhorado

Há muitas razões para tornar uma biblioteca leve: sua aplicação terá um pacote menor, um tempo de execução mais enxuto e um diretório node_modules menor.

Também melhoramos o agrupamento do pacote e agora ele suporta importações de caminho:

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

Se você não estiver usando useSWRInfinite, ele não será incluído em sua aplicação.

Dados de Fallback

Na versão 1.0, há uma nova opção fallback que você pode fornecer qualquer dado pré-buscado como o valor inicial de todos os hooks SWR com chaves específicas:

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

Isso é muito útil para cenários como SSG, SSR e mockup de dados para teste. Verifique a documentação SSG e SSR com Next.js para obter mais detalhes.

Para melhor consistência e para evitar confusão, o antigo initialData agora foi renomeado para fallbackData, que ainda fornece um único valor de fallback para o hook fornecido.

Modo Imutável

Às vezes, você deseja marcar um recurso como imutável se ele nunca for alterado. É melhor desabilitar as revalidações automáticas para ele e fazer a solicitação apenas uma vez. Agora existe um hook auxiliar para tornar isso mais fácil:

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

Ele possui exatamente a mesma API que o hook useSWR, mas nunca será revalidado no foco da guia ou na recuperação da rede. Há também uma nova opção, revalidateIfStale, que você pode usar para controlar o comportamento com precisão. Mais informações podem ser encontradas aqui.

Cache Provider Personalizado

Por padrão, o SWR usa um único cache global para armazenar todos os dados. Na versão 1.0, você pode personalizá-lo com a nova opção provider:

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

Você pode usar esse novo recurso para fazer muitas coisas poderosas. Temos alguns exemplos aqui: Mudar Várias Chaves com RegEx, Cache Persistente Baseado em LocalStorage, Redefinir Cache Entre Casos de Teste.

Esta nova API de cache provider também é mais compatível com a renderização simultânea do React 18. Se você estiver adicionando um cache provider, certifique-se de usar a função global mutate retornada de useSWRConfig().

Você pode ler a documentação dos cache providers para obter mais detalhes.

useSWRConfig()

Há uma nova Hook API para retornar todas as configurações globais, incluindo o cache provider atual e a função global mutate:

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

Mais informações podem ser encontradas aqui.

Middleware

O SWR Middleware fornece uma nova maneira de construir e reutilizar abstrações em cima de hooks SWR:

<SWRConfig value={{ use: [...middleware] }}>
 
// ... ou diretamente no `useSWR`:
useSWR(key, fetcher, { use: [...middleware] })

Muitas ideias novas podem ser implementadas com esse recurso, e criamos alguns exemplos: Request Logger, Keep Previous Data When Change the Key e Serialize Object Keys.

Verifique a API de middleware para obter mais detalhes.

Melhorias e Melhor Cobertura de Teste

Desde 0.x, fizemos centenas de pequenas melhorias e correções de bugs. O SWR agora tem 157 testes que cobrem a maioria dos casos extremos na busca de dados. Leia o Changelog (opens in a new tab) para mais detalhes.

Traduções de Documentação

Graças aos nossos contribuidores (opens in a new tab) e ao recurso i18n da Nextra (opens in a new tab), agora oferecemos Documentação do SWR em seis idiomas diferentes:

• Inglês (opens in a new tab)
• Espanhol (opens in a new tab)
• Chinês Simplificado (opens in a new tab)
• Japonês (opens in a new tab)
• Coreano (opens in a new tab)
• Russo (opens in a new tab)

Guia de Migração

Atualizar imports do useSWRInfinite

useSWRInfinite precisa ser importado de swr/infinite:

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

Se você está usand os tipos correspondentes, atualize o caminho de importação:

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

Mude revalidate para mutate

useSWR não mais retorna o método revalidate, mude para mutate:

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

Renomeie initialData para fallbackData

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

Não Há Mais Fetcher Padrão

O SWR não fornece mais o fetcher padrão (uma chamada fetch que analisa os dados como JSON). A maneira mais fácil de migrar a alteração é usar o componente <SWRConfig>:

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

Recomenda-se usar o mutate retornado pelo hook

Esta não é uma mudança importante, mas agora recomendaremos usar sempre o mutate retornado do hook useSWRConfig:

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

Se você não estiver usando um cache provider, a importação global atual import { mutate } from 'swr' ainda funciona.

Tipos Renomeados

Se você está usando TypeScript, os seguintes nomes de tipo foram alterados para consistência:

Usuários de Recursos Beta e Não Oficiais

Se você estiver usando uma versão beta do SWR ou qualquer API não documentada, esteja ciente das seguintes alterações:

• import { cache } from 'swr' foi removido; use o novo useSWRConfig API no lugar.
• import { createCache } from 'swr' foi removido; use a nova Cache Provider API no lugar.
• revalidateWhenStale foi renomeado para revalidateIfStale.
• middlewares foi renomeado para use.

Changelog

Leia o Changelog completo no GitHub (opens in a new tab).

Qual é o Próximo Passo

Em versões futuras, continuaremos melhorando a biblioteca, mantendo a estabilidade. Também pretendemos adotar futuras versões do React, já que vários novos recursos e melhorias na versão 1.0 já estão se preparando para isso. Além disso, também estamos trabalhando em novos recursos para melhorar a experiência de busca de dados no React e a experiência de uso desta biblioteca.

Se você tiver algum feedback sobre esta versão, por favor nos avise (opens in a new tab).

Agradecimentos

Agradecimentos especiais a Toru Kobayashi (opens in a new tab) e Yixuan Xu (opens in a new tab) por suas contribuições para a biblioteca, e Paco Coursey (opens in a new tab), uttk (opens in a new tab), Tomohiro SHIOYA (opens in a new tab), Markoz Peña (opens in a new tab), SeulGi Choi (opens in a new tab), Fang Lu (opens in a new tab), Valentin Politov (opens in a new tab) por seu trabalho nas traduções e documentos. Este lançamento não pode acontecer sem eles.

Também queremos agradecer a toda a comunidade, nossos 110 colaboradores (opens in a new tab) (+ 45 colaboradores de documentações (opens in a new tab)) e todos que nos ajudaram e nos deram feedback!