TypeScript

Next.js には TypeScript が組み込まれており、create-next-app で新しいプロジェクトを作成する際に必要なパッケージを自動的にインストールし、適切な設定を行います。

既存のプロジェクトに TypeScript を追加するには、ファイルを .ts / .tsx にリネームします。next dev と next build を実行すると、必要な依存関係が自動的にインストールされ、推奨設定オプションを含む tsconfig.json ファイルが追加されます。

補足: 既に jsconfig.json ファイルがある場合、古い jsconfig.json から paths コンパイラオプションを新しい tsconfig.json ファイルにコピーし、古い jsconfig.json ファイルを削除してください。

例

`next.config.ts` の型チェック

next.config.ts で TypeScript を使用し、型をインポートできます。

next.config.ts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* 設定オプションをここに記述 */
}

export default nextConfig

補足: next.config.ts のモジュール解決は現在 CommonJS に限定されています。これにより next.config.ts で ESM のみのパッケージを読み込む際に互換性の問題が発生する可能性があります。

next.config.js ファイルを使用する場合、以下のように JSDoc を使用して IDE で型チェックを追加できます:

next.config.js

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 設定オプションをここに記述 */
}

module.exports = nextConfig

静的生成とサーバーサイドレンダリング

getStaticProps、getStaticPaths、getServerSideProps では、それぞれ GetStaticProps、GetStaticPaths、GetServerSideProps 型を使用できます:

pages/blog/[slug].tsx

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 ルートとの使用

以下は API ルート用の組み込み型を使用する例です:

pages/api/hello.ts

import type { NextApiRequest, NextApiResponse } from 'next'

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

レスポンスデータも型付けできます:

pages/api/hello.ts

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 エラーの無効化

Next.js はプロジェクトに TypeScript エラーがある場合、本番ビルド (next build) を失敗させます。

アプリケーションにエラーがある場合でも Next.js が危険を承知で本番コードを生成するようにしたい場合は、組み込みの型チェックステップを無効にできます。

無効にする場合は、ビルドまたはデプロイプロセスの一部として型チェックを実行していることを確認してください。そうしないと非常に危険です。

next.config.ts を開き、typescript 設定で ignoreBuildErrors オプションを有効にします:

next.config.ts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  typescript: {
    // !! 警告 !!
    // プロジェクトに型エラーがあっても本番ビルドを成功させる
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

補足: ビルド前に tsc --noEmit を実行して TypeScript エラーを自分でチェックできます。これは TypeScript エラーをデプロイ前にチェックしたい CI/CD パイプラインで役立ちます。

カスタム型宣言

カスタム型を宣言する必要がある場合、next-env.d.ts を変更したくなるかもしれません。しかし、このファイルは自動生成されるため、加えた変更は上書きされます。代わりに、新しいファイル（例えば new-types.d.ts）を作成し、tsconfig.json で参照してください:

tsconfig.json

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

バージョン変更点

バージョン	変更点
`v15.0.0`	TypeScript プロジェクト向けに `next.config.ts` サポートが追加されました。
`v13.2.0`	静的に型付けされたリンクがベータで利用可能になりました。
`v12.0.0`	SWC が TypeScript と TSX のコンパイルにデフォルトで使用されるようになり、ビルドが高速化されました。
`v10.2.1`	`tsconfig.json` で有効にした場合のインクリメンタル型チェックサポートが追加されました。

On this page