TypeScript

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

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

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

IDEプラグイン

Next.jsにはカスタムTypeScriptプラグインと型チェッカーが含まれており、VSCodeや他のコードエディタで高度な型チェックと自動補完を利用できます。

VS Codeでプラグインを有効にするには、次の手順を行います：

コマンドパレットを開く（Ctrl/⌘ + Shift + P）
「TypeScript: Select TypeScript Version」を検索
「Use Workspace Version」を選択

これで、ファイルを編集するときにカスタムプラグインが有効になります。next buildを実行すると、カスタム型チェッカーが使用されます。

TypeScriptプラグインは次のことに役立ちます：

segment config optionsに無効な値が渡された場合の警告
利用可能なオプションとコンテキスト内のドキュメントの表示
use clientディレクティブが正しく使用されていることの確認
クライアントフック（useStateなど）がClient Componentsでのみ使用されていることの確認

🎥 視聴: 組み込みのTypeScriptプラグインについて学ぶ → YouTube (3分)

エンドツーエンドの型安全性

Next.jsのApp Routerは強化された型安全性を備えています。これには以下が含まれます：

フェッチ関数とページ間のデータのシリアル化なし：コンポーネント、レイアウト、ページでサーバー上で直接fetchできます。このデータはクライアント側でReactで消費するためにシリアル化（文字列に変換）する必要はありません。代わりに、appはデフォルトでServer Componentsを使用するため、Date、Map、Setなどの値を追加の手順なしで使用できます。以前は、Next.js固有の型を使用してサーバーとクライアントの境界を手動で型付けする必要がありました。
コンポーネント間のデータフローの簡素化：_appをroot レイアウトに置き換えることで、コンポーネントとページ間のデータフローを視覚化しやすくなりました。以前は、個々のpagesと_app間のデータフローは型付けが難しく、混乱を招くバグを引き起こす可能性がありました。App Routerでのコロケートされたデータフェッチにより、これはもはや問題ではありません。

Next.jsでのデータフェッチは、データベースやコンテンツプロバイダーの選択に関して指示的でない限り、可能な限りエンドツーエンドの型安全性を提供します。

通常のTypeScriptで期待されるようにレスポンスデータを型付けできます。例えば：

TypeScript

app/page.tsx
async function getData() {
  const res = await fetch('https://api.example.com/...')
  // 戻り値はシリアル化されません
  // Date, Map, Setなどを返すことができます
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

完全なエンドツーエンドの型安全性を実現するには、データベースやコンテンツプロバイダーがTypeScriptをサポートしている必要があります。これは、ORMや型安全なクエリビルダーを使用することで実現できます。

例

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

Next.jsの設定でTypeScriptを使用し、型をインポートするには、next.config.tsを使用します。

next.config.ts
import type { NextConfig } from 'next'

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

export default nextConfig

Good to know: 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

静的に型付けされたリンク

Next.jsは、next/linkを使用する際のタイプミスやその他のエラーを防ぐためにリンクを静的に型付けし、ページ間のナビゲーション時の型安全性を向上させます。

この機能を利用するには、experimental.typedRoutesを有効にし、プロジェクトがTypeScriptを使用している必要があります。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

Next.jsは、アプリケーション内のすべての既存ルートに関する情報を含むリンク定義を.next/typesに生成し、TypeScriptが無効なリンクについてエディタでフィードバックを提供できるようにします。

現在、実験的なサポートは動的セグメントを含む任意の文字列リテラルを含みます。非リテラル文字列の場合、現在はas Routeでhrefを手動でキャストする必要があります：

import type { Route } from 'next';
import Link from 'next/link'

// hrefが有効なルートであればTypeScriptエラーはありません
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// hrefが無効なルートであればTypeScriptエラーが発生します
<Link href="/aboot" />

next/linkをラップするカスタムコンポーネントでhrefを受け入れるには、ジェネリックを使用します：

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>My Card</div>
    </Link>
  )
}

How does it work?

next devまたはnext buildを実行すると、Next.jsはアプリケーション内のすべての既存ルートに関する情報を含む隠し.d.tsファイルを.next内に生成します（Linkのhref型としてのすべての有効なルート）。この.d.tsファイルはtsconfig.jsonに含まれており、TypeScriptコンパイラはその.d.tsをチェックし、無効なリンクについてエディタでフィードバックを提供します。

非同期Server Componentsと共に

TypeScriptでasync Server Componentを使用するには、TypeScript 5.1.3以上と@types/react 18.2.8以上を使用していることを確認してください。

古いバージョンのTypeScriptを使用している場合、'Promise<Element>' is not a valid JSX elementという型エラーが表示されることがあります。TypeScriptと@types/reactの最新バージョンに更新することで、この問題は解決されるはずです。

インクリメンタル型チェック

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

Good to know: 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`で有効にした場合、インクリメンタル型チェックサポートが追加されました。

IDEプラグイン​

エンドツーエンドの型安全性​

例​

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

静的に型付けされたリンク​

非同期Server Componentsと共に​

インクリメンタル型チェック​

本番環境でのTypeScriptエラーの無効化​

カスタム型宣言​

バージョン履歴​