TypeScript

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

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

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

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 и удалите старый файл.

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

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

Статическая генерация и рендеринг на сервере

Для getStaticProps, getStaticPaths и getServerSideProps вы можете использовать типы GetStaticProps, GetStaticPaths и GetServerSideProps соответственно:

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'

export const getStaticProps = (async (context) => {
  // ...
}) satisfies GetStaticProps

export const getStaticPaths = (async () => {
  // ...
}) satisfies GetStaticPaths

export const getServerSideProps = (async (context) => {
  // ...
}) satisfies GetServerSideProps

Полезно знать: satisfies был добавлен в TypeScript в версии 4.9. Рекомендуем обновиться до последней версии TypeScript.

API Routes

Вот пример использования встроенных типов для API-маршрутов:

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

Вы также можете типизировать данные ответа:

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ name: 'John Doe' })
}

Кастомный App

Если у вас есть кастомный App, вы можете использовать встроенный тип AppProps и переименовать файл в ./pages/_app.tsx:

import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Алиасы путей и 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:

module.exports = {
  typescript: {
    // !! ВНИМАНИЕ !!
    // Опасное разрешение на успешное завершение продакшен-сборки
    // даже при наличии ошибок типов в проекте.
    // !! ВНИМАНИЕ !!
    ignoreBuildErrors: true,
  },
}

Кастомные объявления типов

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

{
  "compilerOptions": {
    "skipLibCheck": true
    //...сокращено...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

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