moai-lang-typescript

クイックリファレンス（30 秒）

TypeScript 5.9 以降の開発スペシャリスト — React 19、Next.js 16、型安全な API パターンを活用したモダンな TypeScript。

自動トリガー：.ts、.tsx、.mts、.cts 拡張子のファイル、TypeScript の設定、React または Next.js のプロジェクト

コアスタック：

• TypeScript 5.9：モジュール評価の遅延、デコレーター、satisfies 演算子
• React 19：サーバーコンポーネント、use フック、アクション、並行処理機能
• Next.js 16：App Router、サーバーアクション、ミドルウェア、ISR/SSG/SSR
• 型安全な API：tRPC 11、Zod 3.23、tanstack-query
• テスト：Vitest、React Testing Library、Playwright

クイックコマンド：

npx create-next-app を使用し、latest、typescript、tailwind、app フラグを指定して Next.js 16 プロジェクトを作成します。npm install で trpc server、client、react-query、zod、tanstack react-query をインストールし、型安全な API スタックを導入します。npm install の D フラグを指定し、vitest、testing-library react、playwright test をインストールしてテストスタックを導入します。

---

実装ガイド（5 分）

TypeScript 5.9 の主な機能

型を拡張せずに型チェックできる Satisfies 演算子：

red、green、blue の文字列リテラルのユニオンとして Colors 型を定義します。red を数値配列、green を 16 進数文字列、blue を数値配列とする palette オブジェクトを作成します。Record<Colors, string | number[]> に対して satisfies 演算子を適用します。これで palette.red は数値配列として推論されるため map メソッドを使用でき、palette.green は文字列として推論されるため toUpperCase を使用できます。

モジュール評価の遅延：

import defer を使い、アスタリスクを名前空間として heavy module path からインポートします。モジュールが必要な関数内で名前空間のプロパティにアクセスすると、初回使用時にモジュールが読み込まれます。

モダンデコレーター Stage 3：

target 関数と ClassMethodDecoratorContext を受け取る logged 関数デコレーターを作成します。メソッド名をログに出力してから、apply で target を呼び出す関数を返します。データを取得するクラスメソッドに logged デコレーターを適用します。

React 19 のパターン

App Router でのサーバーコンポーネントのデフォルト化：

app/users/[id]/page.tsx のページコンポーネントに対し、params を id 文字列を含むオブジェクトの Promise とする PageProps インターフェースを定義します。params を await し、データベースからユーザーを検索し、見つからない場合は notFound を呼び出し、ユーザー名を含む main 要素を返す非同期のデフォルト関数を作成します。

Promise とコンテキストを展開する use フック：

use client ディレクティブを付けたクライアントコンポーネントで、react から use をインポートします。Promise 型の userPromise プロパティを受け取る UserProfile コンポーネントを作成します。use フックに Promise を渡して、解決されるまでサスペンドします。ユーザー名を含む div を返します。

サーバー関数を使ったフォーム処理のアクション：

use server ディレクティブを付けたサーバーアクションファイルで、revalidatePath をインポートします。zod を使い、名前とメールアドレスを検証する CreateUserSchema を定義します。FormData を受け取り、スキーマで解析し、データベースにユーザーを作成してパスを再検証する非同期の createUser 関数を作成します。

フォームの状態を管理する useActionState：

クライアントコンポーネントで useActionState をインポートします。createUser アクションを渡して useActionState を呼び出し、state、action、isPending を分割代入するフォームコンポーネントを作成します。action プロパティ付きのフォーム、保留中は無効になる入力欄、動的なテキストを表示するボタン、state のエラーメッセージを返します。

Next.js 16 App Router

ルート構造：

app ディレクトリには、ルートレイアウト用の layout.tsx、ホームルート用の page.tsx、読み込み UI 用の loading.tsx、エラーバウンダリー用の error.tsx、API ルート用の api/route.ts が含まれます。users などのサブディレクトリには、一覧用の page.tsx と動的ルート用の [id]/page.tsx が含まれます。ルートグループには、(marketing)/about/page.tsx のように括弧を使用します。

メタデータ API：

Metadata 型をインポートします。default と template を含むオブジェクトを title に設定し、文字列の description を指定した metadata オブジェクトをエクスポートします。params を受け取り、params を待機してユーザーを取得し、title にユーザー名を設定したオブジェクトを返す非同期の generateMetadata 関数をエクスポートします。

検証付き Server Actions：

サーバーファイルで、zod、revalidatePath、redirect をインポートします。id、name、email の検証を含む UpdateUserSchema を定義します。prevState と formData を受け取る非同期の updateUser 関数を作成します。safeParse で解析し、失敗した場合はエラーを返し、データベースを更新して、パスを再検証し、リダイレクトします。

tRPC による型安全な API

サーバーのセットアップ：

trpc server から initTRPC と TRPCError をインポートします。initTRPC.context を Context 型とともに呼び出して t を作成し、その後 create を呼び出します。t から router、publicProcedure、protectedProcedure をエクスポートします。protectedProcedure は、セッションのユーザーを確認し、ユーザーがいない場合は UNAUTHORIZED エラーをスローするミドルウェアを使用します。

ルーターの定義：

zod をインポートします。router 関数を使用して userRouter を作成します。publicProcedure を使用して getById プロシージャを定義し、入力スキーマでは id を UUID 文字列として指定し、クエリーでは ID でユーザーを検索します。protectedProcedure を使用して create プロシージャを定義し、入力スキーマでは name と email を指定し、ミューテーションでユーザーを作成します。

クライアントでの使用：

クライアントコンポーネントで、trpc.user.list.useQuery を page パラメーターとともに呼び出す UserList 関数を作成します。data と isLoading を分割代入します。trpc.user.create.useMutation を使用してミューテーションを作成します。読み込み状態またはユーザー一覧を返します。

Zod スキーマのパターン

複雑な検証：

z.object を含む UserSchema を作成します。id は UUID 文字列、name は最小長と最大長を指定し、email はメール形式、role は admin、user、guest の列挙型、createdAt は coerce.date として定義します。strict メソッドを適用します。スキーマから User 型を推論します。id と createdAt を省略し、password と confirmPassword を追加して拡張し、パスワードの一致を検証するカスタムメッセージとパスを指定した refine を追加して、CreateUserSchema を作成します。

状態管理

クライアント状態に Zustand を使用：

zustand とミドルウェアから create をインポートします。user を User または null とし、login メソッドと logout メソッドを含む AuthState インターフェースを定義します。devtools と persist ミドルウェアでラップした create 関数を使用して useAuthStore を作成します。初期ユーザーを null に設定し、login ではユーザーを設定し、logout ではユーザーを null に設定します。persist は auth-storage という名前を使用します。

アトミック状態に Jotai を使用：

jotai から atom を、jotai/utils から atomWithStorage をインポートします。初期値が 0 の countAtom を作成します。countAtom を取得して 2 を掛ける派生アトムとして doubleCountAtom を作成します。ストレージに保存されるライトまたはダークのテーマ用に、atomWithStorage で themeAtom を作成します。

---

高度なパターン

高度な TypeScript パターン、パフォーマンス最適化、テスト戦略、デプロイ設定を含む包括的なドキュメントについては、以下を参照してください。

• 完全な API リファレンス、Context7 ライブラリマッピング、高度な型パターンについては、reference.md を参照してください
• 本番環境向けのコード例、フルスタックパターン、テストテンプレートについては、examples.md を参照してください

Context7 の統合

TypeScript のドキュメントでは、decorators と satisfies のトピックを含む microsoft/TypeScript を使用します。React 19 では、server-components と use-hook を含む facebook/react を使用します。Next.js 16 では、app-router と server-actions を含む vercel/next.js を使用します。tRPC では、procedures と middleware を含む trpc/trpc を使用します。Zod では、schema validation を含む colinhacks/zod を使用します。

相性の良いツール

• UI コンポーネントやスタイル設定のパターンには moai-domain-frontend
• API 設計やデータベース連携には moai-domain-backend
• コンポーネントライブラリの統合には moai-library-shadcn
• テスト戦略やパターンには moai-workflow-testing
• コード品質基準には moai-foundation-quality
• TypeScript アプリケーションのデバッグには moai-essentials-debug

---

トラブルシューティングのクイックガイド

TypeScript のエラー：

型チェックのみを行うには、npx tsc を noEmit フラグ付きで実行します。パフォーマンスのトレースを出力するには、npx tsc を generateTrace フラグと出力ディレクトリを指定して実行します。

React と Next.js の問題：

ビルドエラーを確認するには、npm run build を実行します。ESLint のチェックには、npx next lint を実行します。キャッシュをクリアするには、.next ディレクトリを削除して npm run dev を実行します。

型安全性のパターン：

予期しない値に対してエラーをスローする、never 型のパラメーターを受け取る assertNever 関数を作成します。これは網羅性を確認する switch 文で使用します。値が id プロパティを持つオブジェクトかどうかを確認し、型述語を返す isUser 型ガード関数を作成します。

---

最終更新日：2026-01-11 ステータス：アクティブ（v1.1.0）