Next.js 16 на практике: что изменилось и что переписывать

Мы перевели на Next.js 16 несколько рабочих проектов и собрали список того, что действительно требует внимания. Большая часть изменений обратно совместима, но три вещи придётся править руками, и лучше знать о них до начала обновления.

Асинхронные параметры маршрутов

Самое заметное изменение: params, searchParams, headers и cookies больше не синхронные. Их нужно дожидаться. Это касается каждой динамической страницы и каждого обработчика маршрута, поэтому правок обычно много, но все они однотипные.

// Было
export default function Page({ params }: { params: { slug: string } }) {
  const post = getPost(params.slug)
  return <Article post={post} />
}

// Стало
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = getPost(slug)
  return <Article post={post} />
}

То же самое в generateMetadata и в обработчиках маршрутов. Забытое ожидание проявляется не ошибкой типов, а пустым значением в рантайме, поэтому после правок обязательно прогоните сборку с проверкой типов.

Новая модель кэширования

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

// Кэшируем результат функции
export async function getPricing() {
  "use cache"
  const rows = await db.pricing.findMany()
  return rows
}

// Сброс кэша: второй аргумент задаёт профиль устаревания
import { revalidateTag, updateTag } from "next/cache"

// В обычном коде: помечаем как устаревшее, показываем старое
// значение и обновляем в фоне
revalidateTag("pricing", "max")

// В серверном действии: нужно, чтобы пользователь сразу увидел
// собственное изменение
updateTag("pricing")

Turbopack по умолчанию

Сборщик Turbopack стал стабильным и используется по умолчанию. На наших проектах холодный старт сократился примерно втрое, отклик при правке файла — заметно быстрее. Из подводных камней встретили два.

• Обращение к путям через process.cwd в серверном коде заставляет сборщик трассировать весь проект. Это раздувает бандл и вызывает предупреждение при сборке.
• Часть плагинов, написанных под webpack, не имеет аналога. Проверьте нестандартные настройки сборки до обновления.

Порядок обновления

1. 01Обновите зависимости на отдельной ветке и запустите сборку — она покажет большинство мест с параметрами.
2. 02Пройдите по всем динамическим страницам, обработчикам маршрутов и generateMetadata, добавьте ожидание параметров.
3. 03Прогоните проверку типов: она поймает несоответствия в типах параметров.
4. 04Разберитесь с кэшированием там, где раньше полагались на неявное поведение.
5. 05Проверьте сборку на предупреждения и только затем публикуйте.

Обновление минорной версии фреймворка — работа на день. Обновление, отложенное на два года, превращается в проект на месяц.