TypeScript

Next.js は React アプリケーション構築のための TypeScript ファーストな開発体験を提供します。

必要なパッケージの自動インストールと適切な設定の構成を含む、組み込みの TypeScript サポートを備えています。

さらに、エディター向けの TypeScript プラグイン も提供しています。

🎥 動画で学ぶ: 組み込み TypeScript プラグインについて → YouTube (3分)

新規プロジェクト

create-next-app は現在、デフォルトで TypeScript を同梱しています。

npx create-next-app@latest

既存プロジェクト

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

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

TypeScript プラグイン

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

VS Code でプラグインを有効にするには:

1. コマンドパレットを開く (Ctrl/⌘ + Shift + P)
2. "TypeScript: Select TypeScript Version" を検索
3. "Use Workspace Version" を選択

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

プラグイン機能

TypeScript プラグインは以下で役立ちます:

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

豆知識: 今後さらに機能が追加される予定です。

TypeScript の最低バージョン

import 名の型修飾子 や パフォーマンス改善 などの構文機能を得るためには、少なくとも TypeScript v4.5.2 以上を使用することを強く推奨します。

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

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

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = 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>
  )
}

動作の仕組み

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

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

Next.js 13 では 型安全性が強化されました。これには以下が含まれます:

1. フェッチ関数とページ間のデータシリアライゼーション不要: サーバー上のコンポーネント、レイアウト、ページで直接 fetch できます。このデータはクライアント側で React が消費するために（文字列に変換して）シリアライズする必要がありません。代わりに、app はデフォルトで Server Components を使用するため、Date、Map、Set などの値を特別な手順なしで使用できます。以前は、Next.js 固有の型を使用してサーバーとクライアントの境界を手動で型付けする必要がありました。
2. コンポーネント間のデータフローの合理化: _app の代わりにルートレイアウトを使用することで、コンポーネントとページ間のデータフローを視覚化しやすくなりました。以前は、個々の pages と _app 間のデータフローを型付けするのが難しく、混乱を招くバグが発生することがありました。Next.js 13 の データフェッチングの併置 により、これは問題ではなくなりました。

Next.js のデータフェッチング は、データベースやコンテンツプロバイダーの選択を規定することなく、可能な限りエンドツーエンドの型安全性に近づけています。

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

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 や型安全なクエリビルダーの使用によって実現できます。

非同期 Server Component の TypeScript エラー

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 の最新バージョンに更新することでこの問題は解決します。

サーバーとクライアントコンポーネント間のデータ受け渡し

サーバーとクライアントコンポーネント間で props を通じてデータを渡す場合、ブラウザで使用するためにデータは依然としてシリアライズ（文字列変換）されます。ただし、特別な型は必要ありません。他のコンポーネント間で props を渡す場合と同じように型付けされます。

さらに、レンダリングされないデータはサーバーとクライアント間を移動しない（サーバーに残る）ため、シリアライズされるコードは少なくなります。これは Server Components のサポートによって初めて可能になりました。

パスエイリアスと baseUrl

Next.js は tsconfig.json の "paths" と "baseUrl" オプションを自動的にサポートします。

この機能について詳しくは モジュールパスエイリアスのドキュメント をご覧ください。

next.config.js の型チェック

next.config.js ファイルは Babel や TypeScript でパースされないため JavaScript ファイルである必要がありますが、以下のように JSDoc を使用して IDE で型チェックを追加できます:

// @ts-check

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

module.exports = nextConfig

増分型チェック

v10.2.1 以降、Next.js は tsconfig.json で有効にした場合の 増分型チェック をサポートしています。これは大規模なアプリケーションでの型チェック速度向上に役立ちます。

TypeScript エラーの無視

Next.js はプロジェクトに TypeScript エラーが存在する場合、プロダクションビルド (next build) を失敗させます。

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

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

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

module.exports = {
  typescript: {
    // !! 警告 !!
    // プロジェクトに型エラーがあってもプロダクションビルドを成功させる
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

バージョン変更点