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 = {
  /* config options here */
}
 
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 = {
  /* config options here */
}
 
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: {
    // !! WARN !!
    // Dangerously allow production builds to successfully complete even if
    // your project has type errors.
    // !! WARN !!
    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
    //...truncated...
  },
  "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` で有効化された場合、インクリメンタル型チェックのサポートが追加されました。