GraphQL TS型生成

GraphQL TS型生成

GraphQL スキーマ(SDL)やクエリから TypeScript の型定義、インターフェース、Enum、リゾルバーを自動生成。設定不要・サーバー送信なしでブラウザ上で即座にコード生成できます。

プリセット一覧
出力ターゲットエコシステム
GraphQL スキーマ入力 (SDL / JSON イントロスペクション)
クイックスカラー登録
本番環境対応エクスポート
12Nodes
AST Architecture
Object: 6Interface: 1Enum: 1Input: 1
83%Strict
Nullability Guard

High non-null strictness (safe against unexpected runtime undefined).

正常なスキーマ AST
/**
 * Strongly Typed GraphQL TypeScript Artifacts
 * Generated via ToolsAA In-Browser Codegen Engine [Regime: strict-modern]
 * 100% In-Browser AST synthesis - Zero server upload
 */

type Maybe<T> = T | null;

type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };

/** All Built-In & Custom GraphQL Scalars */
type Scalars = {
  DateTime: string;
};

type Scalars = {
  JSON: Record<string, unknown>;
};

type Scalars = {
  Money: number;
};

type ProductStatus = 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'OUT_OF_STOCK';

type Node = {
  __typename?: string;
  readonly id: string;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type MoneyAmount = {
  __typename?: 'MoneyAmount';
  readonly amount: number;
  readonly currency: string;
};

type ProductVariant = {
  __typename?: 'ProductVariant';
  readonly id: string;
  readonly sku: string;
  readonly title: string;
  readonly price: MoneyAmount;
  readonly inStock: boolean;
  readonly inventoryQuantity: number;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Review = {
  __typename?: 'Review';
  readonly id: string;
  readonly author: string;
  readonly rating: number;
  readonly comment: Maybe<string>;
  readonly metadata: Maybe<Record<string, unknown>>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Product = {
  __typename?: 'Product';
  readonly id: string;
  readonly title: string;
  readonly slug: string;
  readonly description: Maybe<string>;
  readonly status: ProductStatus;
  readonly price: MoneyAmount;
  readonly variants: ReadonlyArray<ProductVariant>;
  readonly reviews: ReadonlyArray<Review>;
  readonly createdAt: string;
  readonly updatedAt: string;
};

type Query = {
  __typename?: 'Query';
  readonly product: Maybe<Product>;
  readonly products: ReadonlyArray<Product>;
};

type Mutation = {
  __typename?: 'Mutation';
  readonly createProduct: Product;
  readonly deleteProduct: boolean;
};

type CreateProductInput = {
  readonly title: string;
  readonly slug: string;
  readonly description?: Maybe<string>;
  readonly price: number;
  readonly currency?: Maybe<String = "USD">;
  readonly status?: Maybe<ProductStatus = DRAFT>;
};
型定義数12
フィールド数40
列挙型数1
ユニオン数0
スカラー型数3
解析所要時間< 1ms
技術リファレンス・アーキテクチャガイド

GraphQL to TypeScript Generator & Codegen ガイド — 技術リファレンス

GraphQL スキーマ (SDL) やクエリ・ミューテーションを、TypeScript の型、interface、enum、リゾルバーへ高精度に自動生成。設定不要・サーバー送信一切なしでブラウザ上で即座に Codegen を実行できます。

GraphQL to TypeScript Generator & Codegen ガイド — 技術リファレンス — クライアントサイド完全ローカル実行アーキテクチャ図
GraphQL to TypeScript Generator & Codegen ガイド — 技術リファレンス — クライアントサイド完全ローカル実行アーキテクチャ図

主要パラメータと設定項目

GraphQL スキーマソース (SDL / イントロスペクション JSON)スキーマ定義ドキュメント (AST 入力)

標準的な GraphQL スキーマ定義言語 (SDL) テキスト、または JSON シリアライズされたイントロスペクション応答 (__schema ルートオブジェクト)。公式の GraphQL 2021年10月仕様の構文に準拠します。

初期値: スキーマ定義言語 (SDL)
Null 許容性・オプショナル戦略コンパイラ Null 許容モード (Enum)

GraphQL の非 null 修飾子 (!) および Null 許容フィールドを TypeScript の型表現へとマッピングします。TypeScript の strictNullChecks 下において、Null 許容フィールドを 'T | null'、'Maybe<T>'、またはオプショナルプロパティ 'field?: T' のいずれで生成するかを制御します。

初期値: Maybe<T> = T | null | undefined
型宣言パラダイム型出力構文 (Enum)

GraphQL の Object 型を TypeScript の 'type' エイリアスまたは 'interface' 宣言のどちらにコンパイルするかを指定します。type エイリアスはインデックスアクセスや直和型(Union)に対応し、interface は拡張可能な SDK での宣言マージ (Declaration Merging) を可能にします。

初期値: type (型エイリアス)
Enum コンパイル形式Enum 表現形式 (Enum)

GraphQL の enum を TypeScript ネイティブの 'enum' ランタイムオブジェクトとしてコンパイルするか、コンパニオン const 辞書を伴う Tree-shaking 可能な文字列リテラル共用体 ('ADMIN' | 'USER') として出力するかを制御します。

初期値: 文字列リテラル共用体 (String Literal Union)
カスタムスカラー型マッピング (ScalarMappingDictionary)マッピング辞書 (Record<string, string>)

ユーザー定義の GraphQL スカラー型を具体的な TypeScript の型へと解決します。デフォルトのマッピング: ID は 'string'、Int は 'number'、Float は 'number'、String は 'string'、Boolean は 'boolean'、DateTime は 'string | Date'。

初期値: DateTime: string, JSON: Record<string, unknown>
イミュータブル / Readonly 配列修飾子イミュータビリティフラグ (Boolean)

有効にすると、すべてのオブジェクトプロパティに 'readonly' 修飾子を付与し、すべてのリスト型を 'ReadonlyArray<T>' でラップします。これにより、Redux や Zustand などの状態管理ストアにおいてコンパイル時のイミュータビリティ(不変性)を強制します。

初期値: true

現場のベストプラクティス・実践Tips

Null 許容性の落とし穴:GraphQL の Null 許容フィールドと TypeScript の undefined

GraphQL において、感嘆符 (!) の付いていない Null 許容出力フィールドは、値が存在しない場合に undefined ではなく明示的な null を返します。一方 TypeScript で 'field?: string' と宣言すると、strictNullChecks 下では undefined は許容されますが明示的な null は型エラーになります。クライアントのレスポンス型では、null を含むサーバーペイロードへのアクセス時に発生するランタイムの TypeError 例外を防ぐため、'field?: string' ではなく常に 'field: Maybe<string>' (string | null) を生成してください。

ネイティブ数値 Enum の回避:ゼロランタイムバンドルを実現する文字列リテラル共用体の活用

TypeScript ネイティブの 'enum' は双方向参照用の JavaScript 即時実行関数 (IIFE) ランタイムオブジェクトを生成するため、最新のバンドラー (Vite、Rollup、esbuild) で Tree-shaking できません。クライアントアプリケーションでは、'type UserRole = "ADMIN" | "MEMBER"' と 'as const' フリーズ配列を組み合わせて出力することで、同等の自動補完とより厳格な型絞り込みを維持しつつ、ランタイムのバンドルオーバーヘッドを 100% 削減できます。

汎用クエリラッパーを廃し TypedDocumentNode によるフラグメントマスキングを導入

単一の巨大なクエリ結果型を出力して fetch 応答を手動で型アサーションする代わりに、TypedDocumentNode<ResultType, VariablesType> インスタンスを生成してください。最新の GraphQL クライアント (Apollo Client 3.7+、urql、graphql-request) は、ドキュメントノードから直接クエリのデータ構造と必要な変数の型を自動推論するため、明示的な型引数の指定が不要になります。

ネットワーク転送用シリアライズ型とメモリ内ドメインモデルの明確な分離

DateTime、JSON、BigInt などのカスタムスカラーは、ネットワーク上では JSON 文字列や数値として送受信されます。Codegen で 'DateTime' を JavaScript の 'Date' にマッピングしてしまうと、標準の JSON.parse() で取得した際に文字列のまま保持され、実行時に日付メソッドのエラー (例: date.toISOString is not a function) が発生します。ネットワーク送受信型には 'string' を採用し、'Date' はパース済みのドメインモデルやデシリアライズ変換処理用に限定してください。

よくある落とし穴とトラブルシューティング

⚠️生成された input オブジェクトで TypeScript コンパイルエラー TS2322: 型 'null' を型 'undefined' に割り当てることはできません が発生する

GraphQL の input オブジェクトにおいて、フィールドの省略は undefined として扱われるのに対し、明示的な null は意図的なリセット・クリアを意味します。tsconfig.json で exactOptionalPropertyTypes を有効化し、Codegen の入力設定で入力引数に 'field?: string | null' を出力するように構成することで、キーの省略と明示的な null ペイロードの送信を型安全に区別してください。

⚠️深くネストされた再帰的スキーマで循環参照の深さが TypeScript コンパイラの制限を超過する

自己参照を持つスキーマ構造 (例: Comment -> replies: [Comment!]! や Category -> children: [Category!]!) は、TS2589「型のインスタンス化が無限に再帰する可能性があります」を引き起こすことがあります。ネストされた再帰的な 'type' エイリアスではなく 'interface' 宣言として型定義を出力することで、TypeScript のインターフェースプロパティ遅延解決メカニズムが機能し、この問題を解消できます。

⚠️イントロスペクション結果の貼り付け時に「Syntax Error: Unexpected token in JSON at position 0」が発生する

'__schema' または 'data.__schema' ルートキーを含む JSON ペイロード全体が貼り付けられていることを確認してください。イントロスペクションクエリを cURL や Postman 経由で取得した場合は、パース前に HTTP レスポンスヘッダーなどのラッパーを除去し、エスケープされた二重引用符のアンエスケープを行ってください。

⚠️Apollo Federation ディレクティブ (@key, @external, @shareable) により未知のディレクティブ解析エラーが発生する

標準の GraphQL 仕様パーサーには、Apollo Federation v1/v2 のスキーマディレクティブがデフォルトでは含まれていません。本ジェネレーターには Federation ディレクティブのスタブが組み込まれているため、「Federation ディレクティブを有効化」トグルをオンにするか、標準の Federation ディレクティブ定義ブロックを SDL の先頭に貼り付けてください。

よくある質問 (FAQ)

GraphQL の Null 許容性は、TypeScript のオプショナルプロパティや null 共用体へどのようにマッピングされますか?▼

GraphQL SDL ではフィールドはデフォルトで Null 許容であり、感嘆符 (!) が付いている場合のみ非 null と見なされます。strictNullChecks を有効にした TypeScript では、非 null フィールド (String!) は 'string' にコンパイルされ、Null 許容フィールド (String) は 'string | null' (または 'Maybe<string>') にコンパイルされます。一方、input オブジェクトの場合は、GraphQL クエリやミューテーションで引数を省略できる仕様になっているため、Null 許容フィールドはオプショナルプロパティ ('field?: string | null') へと変換されます。

GraphQL の enum は TypeScript の enum と文字列リテラル共用体のどちらに変換すべきですか?▼

最新の Web アプリケーションでは、文字列リテラル共用体 ('type Status = "ACTIVE" | "INACTIVE"') の使用を強く推奨します。コンパイル後の JavaScript ランタイムコードが完全にゼロ(ゼロオーバーヘッド)となり、完全な Tree-shaking が可能で、enum オブジェクトをインポートすることなくプレーンな文字列リテラルを渡せるためです。TypeScript ネイティブの enum ('enum Status { Active = "ACTIVE" }') は、ランタイムでのオブジェクトリフレクション、逆引き参照、または既存ライブラリとの互換性が必要な場合にのみ選択してください。

スキーマ型 (Schema Types) Codegen とクライアント操作型 (Client Operation Types) Codegen の違いは何ですか?▼

スキーマ型 Codegen は、バックエンドの GraphQL スキーマ全体(すべての type、input、enum、リゾルバーのシグネチャ)を包括的な TypeScript インターフェースへとコンパイルします。これに対しクライアント操作型 Codegen は、クライアントが発行する個別のクエリードキュメントを解析し、実際に要求されたサブフィールドのみ(セレクションセットやフラグメントを適用)を抽出して、そのクエリが返す JSON ペイロードと完全に一致する正確でフラットなレスポンス型を生成します。

なぜ GraphQL の ID スカラーは TypeScript 専用の型ではなく string や number にシリアライズされるのですか?▼

GraphQL の公式仕様では、ID スカラーは一意の識別子として定義され、レスポンスでは String としてシリアライズされますが、入力時にはクライアントから文字列または整数のどちらを渡すことも許可されています。そのため、TypeScript の Codegen では ID を 'string'(出力型用)または 'string | number'(入力引数用)にマッピングします。異なるエンティティの ID 間で厳格な型安全性を確保したいアプリケーションでは、Branded Type(公称型、例: 'type UserId = string & { readonly __brand: unique symbol }')の導入を推奨します。

関連開発者ツール

全ツール一覧 →
HTML Markdown変換開発者ツール

HTMLやWebクリップをGitHub Flavored Markdown(GFM)に瞬時に変換。インラインスタイルを除去し、テーブルやコードブロックをクリーンなMDファイルとして出力します。

ツールを開く→
テキスト差分比較ツール開発者ツール

テキスト、コード、設定ファイルの差分を高速比較。左右分割やインラインでの文字単位の変更確認、空白の無視、Unified Diff(.patch)の出力に対応。

ツールを開く→
カノニカルタグ生成ツール開発者ツール

有効なrel=canonicalタグやHTTPレスポンスヘッダーを瞬時に作成。不要な追跡パラメータの削除、URL正規化、重複コンテンツによるSEO評価の分散を確実に防止します。

ツールを開く→
cURLをFetchに変換開発者ツール

cURLコマンドを一瞬でFetch APIコードに変換。HTTPヘッダー、認証トークン、Cookie、JSONペイロードを自動解析し、最新のasync/await対応JavaScriptコードを生成します。

ツールを開く→
XMLサイトマップ検証ツール開発者ツール

XMLサイトマップおよびインデックスファイルの構文を瞬時に検証。5万URL制限、50MB容量上限、W3C Datetime(ISO-8601)、hreflang相互リンク、画像拡張、Google Search Console登録エラーを完全チェックします。

ツールを開く→
Google検索結果プレビュー開発者ツール

PC・モバイル対応のGoogle検索結果(SERP)スニペット表示を正確なピクセル幅でシミュレーション。リッチリザルト、サイトリンク、リアルタイムCTRスコア判定でタイトルとディスクリプションの省略を事前検証します。

ツールを開く→