TypeScript

Next.js предоставляет TypeScript-ориентированный опыт разработки для создания React-приложений.

Он включает встроенную поддержку TypeScript для автоматической установки необходимых пакетов и настройки соответствующих параметров.

А также плагин TypeScript для вашего редактора.

🎥 Видео: Узнайте о встроенном плагине TypeScript → YouTube (3 минуты)

Новые проекты

create-next-app теперь по умолчанию использует TypeScript.

Терминал

npx create-next-app@latest

Добавьте TypeScript в свой проект, переименовав файл в .ts / .tsx. Запустите next dev и next build, чтобы автоматически установить необходимые зависимости и добавить файл tsconfig.json с рекомендуемыми настройками.

Если у вас уже был файл jsconfig.json, скопируйте параметр компилятора paths из старого jsconfig.json в новый файл tsconfig.json и удалите старый файл jsconfig.json.

Плагин TypeScript

Next.js включает пользовательский плагин TypeScript и проверку типов, которые могут использовать VSCode и другие редакторы кода для расширенной проверки типов и автодополнения.

Вы можете включить плагин в VS Code следующим образом:

Откройте палитру команд (Ctrl/⌘ + Shift + P)
Найдите "TypeScript: Select TypeScript Version"
Выберите "Use Workspace Version"

Теперь при редактировании файлов будет активирован пользовательский плагин. При запуске next build будет использоваться пользовательская проверка типов.

Возможности плагина

Плагин TypeScript может помочь с:

Предупреждением о передаче недопустимых значений для опций конфигурации сегментов.
Отображением доступных опций и документации в контексте.
Проверкой правильности использования директивы use client.
Гарантией того, что клиентские хуки (например, useState) используются только в клиентских компонентах.

Полезно знать: В будущем будут добавлены новые возможности.

Минимальная версия TypeScript

Настоятельно рекомендуется использовать как минимум TypeScript v4.5.2 для получения таких возможностей синтаксиса, как модификаторы типов для имён импорта и улучшения производительности.

Статически типизированные ссылки

Next.js может статически типизировать ссылки, чтобы предотвратить опечатки и другие ошибки при использовании next/link, улучшая безопасность типов при навигации между страницами.

Чтобы включить эту функцию, необходимо активировать experimental.typedRoutes и использовать TypeScript в проекте.

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig

Next.js сгенерирует определение ссылок в .next/types, содержащее информацию обо всех существующих маршрутах вашего приложения, которую TypeScript сможет использовать для предоставления обратной связи в вашем редакторе о недопустимых ссылках.

В настоящее время экспериментальная поддержка включает любые строковые литералы, включая динамические сегменты. Для нелитеральных строк вам вручную нужно привести href с помощью as Route:

import type { Route } from 'next';
import Link from 'next/link'

// Не будет ошибок TypeScript, если href является допустимым маршрутом
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// Будут ошибки TypeScript, если href не является допустимым маршрутом
<Link href="/aboot" />

Чтобы принимать href в пользовательском компоненте, оборачивающем next/link, используйте дженерик:

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>Моя карточка</div>
    </Link>
  )
}

Как это работает?

При запуске next dev или next build Next.js генерирует скрытый файл .d.ts внутри .next, содержащий информацию обо всех существующих маршрутах вашего приложения (все допустимые маршруты как тип href для Link). Этот файл .d.ts включается в tsconfig.json, и компилятор TypeScript будет проверять его и предоставлять обратную связь в вашем редакторе о недопустимых ссылках.

Сквозная безопасность типов

Next.js 13 предлагает улучшенную безопасность типов. Это включает:

Отсутствие сериализации данных между функцией получения данных и страницей: Вы можете использовать fetch непосредственно в компонентах, макетах и страницах на сервере. Эти данные не нужно сериализовать (преобразовывать в строку) для передачи на клиентскую сторону. Поскольку app по умолчанию использует серверные компоненты, мы можем использовать значения типа Date, Map, Set и другие без дополнительных шагов. Ранее требовалось вручную типизировать границу между сервером и клиентом с помощью специфичных для Next.js типов.
Упрощённый поток данных между компонентами: С удалением _app в пользу корневых макетов стало проще визуализировать поток данных между компонентами и страницами. Ранее типизация данных, передаваемых между отдельными pages и _app, была сложной и могла приводить к запутанным ошибкам. С совместным получением данных в Next.js 13 эта проблема устранена.

Получение данных в Next.js теперь обеспечивает максимально возможную сквозную безопасность типов без привязки к выбору базы данных или провайдера контента.

Мы можем типизировать данные ответа, как вы ожидаете в обычном TypeScript. Например:

app/page.tsx

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // Возвращаемое значение *не* сериализуется
  // Вы можете возвращать Date, Map, Set и т.д.
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

Для полной сквозной безопасности типов также требуется, чтобы ваша база данных или провайдер контента поддерживали TypeScript. Это может быть реализовано с помощью ORM или типобезопасного построителя запросов.

Ошибка TypeScript в асинхронных серверных компонентах

Для использования асинхронных серверных компонентов с TypeScript убедитесь, что вы используете TypeScript 5.1.3 или новее и @types/react 18.2.8 или новее.

Если вы используете более старую версию TypeScript, вы можете увидеть ошибку типа 'Promise<Element>' is not a valid JSX element. Обновление до последней версии TypeScript и @types/react должно решить эту проблему.

Передача данных между серверными и клиентскими компонентами

При передаче данных между серверным и клиентским компонентом через пропсы данные всё ещё сериализуются (преобразуются в строку) для использования в браузере. Однако для этого не требуется специальный тип. Типизация происходит так же, как и при передаче любых других пропсов между компонентами.

Кроме того, меньше кода требует сериализации, поскольку неотрисованные данные не передаются между сервером и клиентом (они остаются на сервере). Это стало возможным только благодаря поддержке серверных компонентов.

Псевдонимы путей и baseUrl

Next.js автоматически поддерживает параметры "paths" и "baseUrl" в tsconfig.json.

Подробнее об этой функции вы можете узнать в документации Псевдонимы модулей и абсолютные импорты.

Проверка типов в next.config.js

Файл next.config.js должен быть JavaScript-файлом, так как он не обрабатывается Babel или TypeScript, однако вы можете добавить проверку типов в вашей IDE с помощью JSDoc, как показано ниже:

// @ts-check

/**
 * @type {import('next').NextConfig}
 **/
const nextConfig = {
  /* параметры конфигурации здесь */
}

module.exports = nextConfig

Инкрементальная проверка типов

Начиная с версии v10.2.1 Next.js поддерживает инкрементальную проверку типов, если она включена в вашем tsconfig.json. Это может помочь ускорить проверку типов в больших приложениях.

Игнорирование ошибок TypeScript

Next.js завершает продакшен-сборку (next build) с ошибкой, если в вашем проекте есть ошибки TypeScript.

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

Если проверка отключена, убедитесь, что вы выполняете проверку типов как часть процесса сборки или развёртывания, иначе это может быть очень опасно.

Откройте next.config.js и включите параметр ignoreBuildErrors в конфигурации typescript: