Представляем SWR 1.0

Почти 2 года назад мы сделали SWR — крошечную React библиотеку с открытым исходным кодом (opens in a new tab) для выборки данных, которую люди полюбили. Сегодня мы приближаемся к еще одной вехе: версии 1.0 SWR!

Что нового

Уменьшенный размер

Производительность — одна из важнейших характеристик SWR. В версии 1.0 мы значительно уменьшили размер библиотеки, при этом не удалив никаких существующих функций:

• Ядро меньше на 41% (на 24% меньше при сжатии gzip, 3,9 КБ)
• Размер установленного пакета на 52% меньше
• Улучшен tree-shaking

Есть много причин сделать библиотеку облегченной: ваше приложение будет иметь меньший пакет, более компактную среду выполнения и меньший каталог node_modules.

Мы также улучшили бандлинг пакета, и теперь он поддерживает импорт путей:

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

Если вы не используете useSWRInfinite, он не будет включен в ваше приложение.

Резервные данные

В версии 1.0 появилась новая опция fallback, которой вы можете предоставить любые предварительно выбранные данные в качестве начального значения всех хуков SWR с определенными ключами:

<SWRConfig value={{
  fallback: {
    '/api/user': { name: 'Иван', ... },
    '/api/items': ...,
    ...
  }
}}>
  <App/>
</SWRConfig>

Это очень полезно для таких сценариев, как SSG, SSR и макетирования данных для тестирования. Подробности смотрите в документации Next.js SSG и SSR.

Для большей согласованности и во избежание путаницы старый initialData теперь переименован в fallbackData, который по-прежнему предоставляет единое резервное значение для заданного хука.

Неизменяемый режим

Иногда вы хотите пометить ресурс как неизменный, если он никогда не изменится. Лучше отключить для него автоматическую ревалидацию и сделать запрос только один раз. Теперь есть вспомогательный хук, чтобы упростить эту задачу:

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

Он имеет тот же API, что и хук useSWR, но он никогда не будет ревалидировать при фокусировке вкладки или восстановлении сети. Также есть новая опция revalidateIfStale, которую можно использовать для точного управления поведением. Более подробную информацию можно найти здесь.

Пользовательский поставщик кеша

По умолчанию SWR использует единый глобальный кеш для хранения всех данных. В версии 1.0 вы можете настроить его с помощью новой опции provider:

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

Вы можете использовать эту новую функцию для множества полезных вещей. У нас есть пара примеров: Изменение нескольких ключей с помощью RegEx,, Постоянный кеш на основе локального хранилища, Сброс кеша между тестами.

Этот новый API кеш-провайдера также более совместим с параллельным рендерингом React 18. Если вы добавляете кеш-провайдера, обязательно используйте глобальную функцию mutate, возвращаемую из useSWRConfig().

Вы можете прочитать документацию Cache Provider для более подробной информации.

useSWRConfig()

Появился новый Hook API для возврата всех глобальных конфигураций, включая текущего поставщика кеша и глобальной функции mutate:

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

Более подробно можно почитать здесь.

Промежуточное программное обеспечение (ППО) (Middleware)

SWR промежуточное ПО предоставляет вам новый способ создания и повторного использования абстракций поверх хуков SWR:

<SWRConfig value={{ use: [...middleware] }}>
 
// ... или напрямую в `useSWR`:
useSWR(key, fetcher, { use: [...middleware] })

С помощью этой функции можно реализовать множество новых идей, и мы создали несколько примеров: Регистратор запросов, Сохранение предыдущих данных при изменении ключа и Сериализация ключей объекта.

Смотрите ППО API для более подробной информации.

Улучшения и лучший охват тестов

Начиная с версии 0.x мы внесли сотни небольших улучшений и исправлений. SWR теперь имеет 157 тестов, которые охватывают большинство крайних случаев при выборке данных. Прочтите журнал изменений (opens in a new tab) для более подробной информации.

Перевод документации

Благодаря нашим контрибютерам (opens in a new tab) и функции i18n (opens in a new tab) от Nextra, теперь мы предлагаем документацию по SWR на шести разных языках:

• Английский (opens in a new tab)
• Испанский (opens in a new tab)
• Упрощенный китайский (opens in a new tab)
• Японский (opens in a new tab)
• Корейский (opens in a new tab)
• Русский (opens in a new tab)

Руководство по миграции

Обновите импорты useSWRInfinite

useSWRInfinite должен быть импортирован из swr/infinite:

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

Если вы используете соответствующие типы, обновите и путь импорта:

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

Измените revalidate на mutate

useSWR больше не возвращает метод revalidate, вместо этого измените его на mutate:

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

Переименуйте initialData на fallbackData

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

Больше нет Fetcher'a по умолчанию

SWR больше не предоставляет fetcher по умолчанию (вызов fetch, который анализирует данные как JSON). Самый простой способ перенести изменение — использовать компонент <SWRConfig>:

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

Рекомендуем использовать mutate возвращаемый хуком

Это не критическое изменение, но теперь мы рекомендуем всегда использовать mutate, возвращаемый хуком useSWRConfig:

- import { mutate } from 'swr'
+ import { useSWRConfig } from 'swr'
 
 
  function Foo () {
+   const { mutate } = useSWRConfig()
 
    return <button onClick={() => mutate('key')}>
      Ключ мутации
    </button>
  }

Если вы не используете кеш-провайдер, текущий глобальный импорт import { mutate } from 'swr' по-прежнему работает.

Переименованные типы

Если вы используете TypeScript, следующие имена типов были изменены для согласованности:

Пользователям бета-версии и неофициальных функций

Если вы используете бета-версию SWR или какие-либо недокументированные API, обратите внимание на следующие изменения:

• import { cache } from 'swr' удалено; используйте новое useSWRConfig API вместо него.
• import { createCache } from 'swr' удалено; используйте новое Cache Provider API вместо него.
• revalidateWhenStale переименовано в revalidateIfStale.
• middlewares переименовано в use.

Журнал изменений

Прочитайте весь журнал изменений на GitHub (opens in a new tab).

Что дальше

В будущих релизах мы продолжим улучшать библиотеку, сохраняя при этом стабильность. Мы также стремимся охватить будущие версии React, поскольку для этого уже готовятся несколько новых функций и улучшений в 1.0. Кроме того, мы также работаем над новыми функциями, чтобы улучшить получение данных в React и удобство использования этой библиотеки.

Если у вас есть какие-либо отзывы об этом выпуске, пожалуйста, сообщите нам об этом (opens in a new tab).

Спасибо!

Особая благодарность Toru Kobayashi (opens in a new tab) и Yixuan Xu (opens in a new tab) за их вклад в библиотеку, и 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), Валентину Политову (opens in a new tab) за их труд над переводом документации. Этот релиз не состоялся бы без них.

Мы также хотим поблагодарить всё сообщество, наших 110 контрибютеров (opens in a new tab) (+ 45 контрибютеров документации (opens in a new tab)) и всех, кто помогал и оставлял нам отзывы!