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やその他のコードエディタで高度な型チェックとオートコンプリートに使用できます。

VSCodeでプラグインを有効にするには、以下の手順を実行します：

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

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

TypeScriptプラグインがサポートする機能：

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

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

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

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

データのシリアライズなし: サーバーでコンポーネント、レイアウト、およびページ内で直接fetchできます。このデータは、クライアント側でReactで利用するためにシリアライズ（文字列に変換）する必要はありません。代わりに、appがデフォルトでServer Componentsを使用するため、Date、Map、Setなどの値を追加の手順なしで使用できます。以前は、Next.js固有の型を使用してサーバーとクライアント間のボーダーを手動でタイプする必要がありました。
コンポーネント間のデータフローの合理化: _appをroot レイアウトに置き換えることで、コンポーネントとページ間のデータフローを視覚化しやすくなりました。以前は、個々のpagesと_appの間のデータフローがタイプしにくく、混乱を招くバグを引き起こす可能性がありました。colocated data fetchingと呼ばれるデータ取得により、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`の型チェック

TypeScriptを使用し、Next.jsの設定で型をインポートするには、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がエディタで無効なリンクについてフィードバックを提供できるようにします。

現在、実験的なサポートには動的セグメントを含むすべての文字列リテラルが含まれています。非リテラル文字列の場合、現在は次のようにhrefを手動でas Routeとしてキャストする必要があります：

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

仕組みは？

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

Async Server Componentと共に

asyncサーバーコンポーネントをTypeScriptで使用するには、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: {
    // !! WARN !!
    // アプリケーションに型のエラーがある場合でも
    // 本番ビルドの完了を成功させることを危険性を承知で許可します。
    // !! WARN !!
    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
    //...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`で有効になっている場合、インクリメンタル型チェックが追加されました。

IDEプラグイン​

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

例​

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

静的型付きリンク​

Async Server Componentと共に​

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

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

カスタム型定義​

バージョン履歴​