TypeScript

Next.js имеет встроенную поддержку TypeScript, автоматически устанавливая необходимые пакеты и настраивая параметры при создании нового проекта с помощью create-next-app.

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

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

Примеры

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

Вы можете использовать TypeScript и импортировать типы в конфигурации Next.js через next.config.ts.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* параметры конфигурации здесь */
}

export default nextConfig

Полезно знать: Разрешение модулей в next.config.ts в настоящее время ограничено CommonJS. Это может вызвать несовместимости с пакетами, работающими только с ESM, при загрузке в next.config.ts.

При использовании файла next.config.js вы можете добавить проверку типов в вашей IDE через JSDoc, как показано ниже:

// @ts-check

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

module.exports = nextConfig

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

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

import type { 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 Routes:

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} />
}

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

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

Отключение ошибок TypeScript в production

Next.js завершает production сборку (next build) с ошибкой, если в проекте присутствуют ошибки TypeScript.

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

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

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

import type { NextConfig } from 'next'

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

export default nextConfig

Полезно знать: Вы можете запустить tsc --noEmit для самостоятельной проверки ошибок TypeScript перед сборкой. Это полезно для CI/CD пайплайнов, где вы хотите проверить ошибки TypeScript перед развертыванием.

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

Когда вам нужно объявить пользовательские типы, может возникнуть соблазн изменить 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"]
}

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