Menu

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を使用して、Next.js設定で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エラーの無効化

プロジェクトにTypeScriptエラーがある場合、Next.jsは本番ビルド（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

補足: ビルド前にTypeScriptエラーをチェックするには、tsc --noEmitを実行できます。これはデプロイ前に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.0TypeScriptプロジェクト用のnext.config.tsサポートが追加されました。
v13.2.0静的に型付けされたリンクがベータ版で利用可能になりました。
v12.0.0より高速なビルドのためにSWCがデフォルトでTypeScriptとTSXをコンパイルするようになりました。
v10.2.1tsconfig.jsonで有効にするとインクリメンタル型チェックのサポートが追加されました。