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, выполнив следующие действия:

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

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

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

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

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

Важно знать: В будущем будут добавлены дополнительные функции.

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

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

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

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

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

/** @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'
 
// No TypeScript errors if href is a valid route
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />
 
// TypeScript errors if href is not a valid route
<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>My Card</div>
    </Link>
  )
}

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

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

Безопасность типов на всех этапах

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

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

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

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

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // The return value is *not* serialized
  // You can return Date, Map, Set, etc.
  return res.json()
}
 
export default async function Page() {
  const name = await getData()
 
  return '...'
}

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

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

Чтобы использовать серверный компонент async с 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 автоматически поддерживает параметры tsconfig.json "paths" и "baseUrl".

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

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

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

// @ts-check
 
/**
 * @type {import('next').NextConfig}
 **/
const nextConfig = {
  /* config options here */
}
 
module.exports = nextConfig

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

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

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

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

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

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

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

module.exports = {
  typescript: {
    // !! WARN !!
    // Dangerously allow production builds to successfully complete even if
    // your project has type errors.
    // !! WARN !!
    ignoreBuildErrors: true,
  },
}

Пользовательские объявления типов

Когда вам нужно объявить пользовательские типы, вы можете быть искушены изменить файл next-env.d.ts. Однако этот файл генерируется автоматически, поэтому любые изменения, которые вы внесёте, будут перезаписаны. Вместо этого вы должны создать новый файл, назовём его new-types.d.ts, и сослаться на него в своём tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
    //...truncated...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

Изменения версий