【TypeScript × GraphQL】完全ガイド｜graphql-codegen・Apollo Client・型安全なクエリ・スキーマ設計を徹底解説

# GraphQL スキーマ定義ntype User {n  id: ID!            # string（non-null）n  name: String!      # string（non-null）n  email: String!     # string（non-null）n  age: Int           # number | null（nullable）n  role: UserRole!    # enumn  posts: [Post!]!    # Post[]（non-null配列）n  createdAt: DateTime! # カスタムスカラー → Date にマッピングn}nnenum UserRole {n  ADMINn  USERn  GUESTn}nntype Query {n  user(id: ID!): User        # User | nulln  users: [User!]!            # User[]n}

// ↑ スキーマから自動生成される TypeScript 型（イメージ）nexport type User = {n  __typename?: 'User';n  id: string;n  name: string;n  email: string;n  age?: number | null;n  role: UserRole;n  posts: Post[];n  createdAt: Date;  // カスタムスカラーマッピング後n};nnexport enum UserRole {n  Admin = 'ADMIN',n  User = 'USER',n  Guest = 'GUEST'n}nnexport type Query = {n  __typename?: 'Query';n  user?: User | null;n  users: User[];n};

# 基本パッケージnnpm install -D @graphql-codegen/cli @graphql-codegen/client-presetnn# TypeScript プラグイン（client-preset に含まれる）n# npm install -D @graphql-codegen/typescript @graphql-codegen/typescript-operationsnn# Apollo Client を使う場合nnpm install @apollo/client graphqlnn# urql を使う場合n# npm install urql @urql/core graphql

// codegen.tsnimport type { CodegenConfig } from '@graphql-codegen/cli'nnconst config: CodegenConfig = {n  schema: 'http://localhost:4000/graphql',  // GraphQL サーバーのエンドポイントn  // または schema: './src/schema.graphql'  // ローカルのスキーマファイルnn  documents: ['src/**/*.graphql', 'src/**/*.tsx'],  // クエリを含むファイルnn  generates: {n    './src/generated/graphql.ts': {n      plugins: [],n      preset: 'client',n      config: {n        // カスタムスカラーの TypeScript 型マッピングn        scalars: {n          DateTime: 'Date',n          JSON: 'Record<string, unknown>',n          Upload: 'File',n        },n        // 生成する型の設定n        enumsAsTypes: true,  // enum を union type として生成n        avoidOptionals: false,n        nonOptionalTypename: true,n      }n    }n  }n}nnexport default config

{n  "scripts": {n    "codegen": "graphql-codegen --config codegen.ts",n    "codegen:watch": "graphql-codegen --config codegen.ts --watch"n  }n}

# 型を生成（または更新）nnpm run codegennn# 開発中はウォッチモードで自動再生成nnpm run codegen:watch

// src/generated/graphql.ts（自動生成・手動編集禁止）nexport type Maybe<T> = T | null;nexport type Scalars = {n  ID: { input: string; output: string; }n  String: { input: string; output: string; }n  Boolean: { input: boolean; output: boolean; }n  Int: { input: number; output: number; }n  Float: { input: number; output: number; }n  DateTime: { input: Date; output: Date; }  // カスタムスカラーn};nnexport type User = {n  __typename?: 'User';n  id: Scalars['ID']['output'];n  name: Scalars['String']['output'];n  email: Scalars['String']['output'];n  age?: Maybe<Scalars['Int']['output']>;n  role: UserRole;n  posts: Array<Post>;n  createdAt: Scalars['DateTime']['output'];n};nn// クエリの型（クエリごとに生成される）nexport type GetUserQueryVariables = Exact<{n  id: Scalars['ID']['input'];n}>;nnexport type GetUserQuery = {n  __typename?: 'Query';n  user?: {n    __typename?: 'User';n    id: string;n    name: string;n    email: string;n    role: UserRole;n  } | null;n};

// src/lib/apolloClient.tsnimport { ApolloClient, InMemoryCache, createHttpLink, from } from '@apollo/client'nimport { onError } from '@apollo/client/link/error'nnconst httpLink = createHttpLink({n  uri: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT ?? 'http://localhost:4000/graphql',n  credentials: 'include',  // Cookie 認証の場合n})nn// エラーハンドリングリンクnconst errorLink = onError(({ graphQLErrors, networkError }) => {n  if (graphQLErrors) {n    graphQLErrors.forEach(({ message, locations, path }) => {n      console.error(`[GraphQL error]: ${message}, Location: ${locations}, Path: ${path}`)n    })n  }n  if (networkError) {n    console.error(`[Network error]: ${networkError}`)n  }n})nnexport const apolloClient = new ApolloClient({n  link: from([errorLink, httpLink]),n  cache: new InMemoryCache({n    typePolicies: {n      User: {n        keyFields: ['id'],  // キャッシュのキー設定n      }n    }n  }),n})

# src/queries/user.graphqlnquery GetUser($id: ID!) {n  user(id: $id) {n    idn    namen    emailn    rolen    createdAtn  }n}nnquery GetUsers {n  users {n    idn    namen    emailn    rolen  }n}

// src/components/UserProfile.tsx（React × Apollo Client）nimport { useQuery } from '@apollo/client'nimport { graphql } from '@/generated'  // client-preset の場合nn// client-preset では gql タグの代わりに graphql() 関数を使うnconst GET_USER = graphql(`n  query GetUser($id: ID!) {n    user(id: $id) {n      idn      namen      emailn      rolen      createdAtn    }n  }n`)nninterface Props {n  userId: stringn}nnexport function UserProfile({ userId }: Props) {n  // useQuery に型引数は不要（GET_USER から自動推論）n  const { data, loading, error } = useQuery(GET_USER, {n    variables: { id: userId },  // { id: string } として型チェックされるn  })nn  if (loading) return <div>読み込み中...</div>n  if (error) return <div>エラー: {error.message}</div>nn  // data.user は GetUserQuery['user'] の型を持つn  // → { id: string; name: string; email: string; role: UserRole; createdAt: Date } | nulln  const user = data?.usern  if (!user) return <div>ユーザーが見つかりません</div>nn  return (n    <div>n      <h2>{user.name}</h2>  {/* user.name → string（型チェックあり）*/}n      <p>{user.email}</p>n      <span>{user.role}</span>  {/* UserRole 型として推論 */}n    </div>n  )n}

# src/queries/user.graphql（追記）nmutation CreateUser($input: CreateUserInput!) {n  createUser(input: $input) {n    idn    namen    emailn    rolen  }n}nnmutation UpdateUser($id: ID!, $input: UpdateUserInput!) {n  updateUser(id: $id, input: $input) {n    idn    namen    emailn  }n}

// src/components/CreateUserForm.tsxnimport { useMutation } from '@apollo/client'nimport { graphql } from '@/generated'nimport { UserRole } from '@/generated/graphql'nnconst CREATE_USER = graphql(`n  mutation CreateUser($input: CreateUserInput!) {n    createUser(input: $input) {n      idn      namen      emailn      rolen    }n  }n`)nnexport function CreateUserForm() {n  // useMutation も CREATE_USER から型が自動推論されるn  const [createUser, { loading, error }] = useMutation(CREATE_USER, {n    // キャッシュの更新n    update(cache, { data }) {n      if (!data?.createUser) returnn      // キャッシュに新しいユーザーを追加n      cache.modify({n        fields: {n          users(existingUsers = []) {n            return [...existingUsers, data.createUser]n          }n        }n      })n    }n  })nn  async function handleSubmit(formData: FormData) {n    const name = formData.get('name') as stringn    const email = formData.get('email') as stringnn    try {n      const { data } = await createUser({n        variables: {n          input: {n            name,n            email,n            role: UserRole.User,  // 型安全な enum 値n          }n        }n      })n      // data.createUser の型は CreateUserMutation['createUser']n      console.log('作成されたユーザー:', data?.createUser.id)n    } catch (e) {n      console.error(e)n    }n  }nn  return (n    <form action={handleSubmit}>n      <input name="name" placeholder="名前" required />n      <input name="email" type="email" placeholder="メール" required />n      <button type="submit" disabled={loading}>n        {loading ? '作成中...' : 'ユーザー作成'}n      </button>n      {error && <p>エラー: {error.message}</p>}n    </form>n  )n}

npm install @apollo/client graphql-ws

// src/lib/apolloClient.ts（サブスクリプション対応版）nimport {n  ApolloClient, InMemoryCache,n  createHttpLink, split, fromn} from '@apollo/client'nimport { GraphQLWsLink } from '@apollo/client/link/subscriptions'nimport { createClient } from 'graphql-ws'nimport { getMainDefinition } from '@apollo/client/utilities'nnconst httpLink = createHttpLink({n  uri: process.env.NEXT_PUBLIC_GRAPHQL_HTTP_ENDPOINT ?? 'http://localhost:4000/graphql',n})nn// WebSocket リンク（サブスクリプション専用）nconst wsLink = new GraphQLWsLink(n  createClient({n    url: process.env.NEXT_PUBLIC_GRAPHQL_WS_ENDPOINT ?? 'ws://localhost:4000/graphql',n    connectionParams: () => ({n      // 認証トークンを WebSocket 接続時に送るn      Authorization: `Bearer ${localStorage.getItem('token') ?? ''}`,n    }),n  })n)nn// クエリ・ミューテーション → HTTP、サブスクリプション → WebSocket に振り分けnconst splitLink = split(n  ({ query }) => {n    const definition = getMainDefinition(query)n    return (n      definition.kind === 'OperationDefinition' &&n      definition.operation === 'subscription'n    )n  },n  wsLink,   // サブスクリプションは WebSocket へn  httpLink  // それ以外は HTTP へn)nnexport const apolloClient = new ApolloClient({n  link: from([splitLink]),n  cache: new InMemoryCache(),n})

# リアルタイム通信（WebSocket 経由）nsubscription OnMessageAdded($roomId: ID!) {n  messageAdded(roomId: $roomId) {n    idn    contentn    sender {n      idn      namen    }n    createdAtn  }n}

// src/components/ChatRoom.tsxnimport { useSubscription } from '@apollo/client'nimport { graphql } from '@/generated'nnconst ON_MESSAGE_ADDED = graphql(`n  subscription OnMessageAdded($roomId: ID!) {n    messageAdded(roomId: $roomId) {n      idn      contentn      sender {n        idn        namen      }n      createdAtn    }n  }n`)nnexport function ChatRoom({ roomId }: { roomId: string }) {n  const { data, loading } = useSubscription(ON_MESSAGE_ADDED, {n    variables: { roomId },n  })nn  // data.messageAdded は OnMessageAddedSubscription['messageAdded'] 型n  const message = data?.messageAddednn  return (n    <div>n      {loading && <span>接続中...</span>}n      {message && (n        <div>n          <strong>{message.sender.name}</strong>: {message.content}n        </div>n      )}n    </div>n  )n}

# src/fragments/user.graphqlnfragment UserBasicFields on User {n  idn  namen  emailn}nnfragment UserDetailFields on User {n  ...UserBasicFieldsn  agen  rolen  createdAtn  posts {n    idn    titlen  }n}

// src/components/UserCard.tsxnimport { FragmentType, useFragment, graphql } from '@/generated'nn// フラグメントの型を定義（client-preset の useFragment パターン）nconst UserCardFragment = graphql(`n  fragment UserCardFields on User {n    idn    namen    emailn    rolen  }n`)nninterface Props {n  // FragmentType でフラグメントの型を参照n  user: FragmentType<typeof UserCardFragment>n}nnexport function UserCard({ user: userFragment }: Props) {n  // useFragment でデータを展開（フラグメントマスキング解除）n  const user = useFragment(UserCardFragment, userFragment)n  // user は { id: string; name: string; email: string; role: UserRole } として推論nn  return (n    <div className="user-card">n      <h3>{user.name}</h3>n      <p>{user.email}</p>n      <span>{user.role}</span>n    </div>n  )n}

// codegen.ts の scalars 設定nconst config: CodegenConfig = {n  generates: {n    './src/generated/graphql.ts': {n      preset: 'client',n      config: {n        scalars: {n          // 日時n          DateTime: 'Date',n          Date: 'string',          // YYYY-MM-DD 形式の文字列の場合n          Time: 'string',nn          // JSON 型n          JSON: 'Record<string, unknown>',n          JSONObject: 'Record<string, unknown>',nn          // ファイルアップロードn          Upload: 'File',nn          // UUIDn          UUID: 'string',nn          // カスタムの厳密な型n          EmailAddress: 'string',n          URL: 'string',n          PositiveInt: 'number',n        }n      }n    }n  }n}

// Apollo Link でカスタムスカラーを変換するnimport { ApolloLink } from '@apollo/client'nn// レスポンスの DateTime 文字列を Date オブジェクトに変換するリンクnfunction isDateString(value: unknown): value is string {n  return typeof value === 'string' && /^d{4}-d{2}-d{2}Td{2}:d{2}:d{2}/.test(value)n}nnfunction convertDates(obj: unknown): unknown {n  if (obj === null || obj === undefined) return objn  if (isDateString(obj)) return new Date(obj)n  if (Array.isArray(obj)) return obj.map(convertDates)n  if (typeof obj === 'object') {n    return Object.fromEntries(n      Object.entries(obj as Record<string, unknown>).map(n        ([key, value]) => [key, convertDates(value)]n      )n    )n  }n  return objn}nnconst dateConversionLink = new ApolloLink((operation, forward) => {n  return forward(operation).map((response) => {n    if (response.data) {n      response.data = convertDates(response.data) as typeof response.datan    }n    return responsen  })n})

npm install urql @urql/core graphqln# TypeScript の型定義は graphql パッケージに含まれる

// src/lib/urqlClient.tsnimport { createClient, cacheExchange, fetchExchange } from 'urql'nnexport const urqlClient = createClient({n  url: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT ?? 'http://localhost:4000/graphql',n  exchanges: [cacheExchange, fetchExchange],n  fetchOptions: () => ({n    headers: {n      Authorization: `Bearer ${getToken()}`,  // 認証トークンn    }n  })n})

// src/components/UserList.tsx（urql + client-preset）nimport { useQuery } from 'urql'nimport { graphql } from '@/generated'nnconst GET_USERS = graphql(`n  query GetUsers {n    users {n      idn      namen      emailn      rolen    }n  }n`)nnexport function UserList() {n  // urql の useQuery も codegen の型を自動推論n  const [result] = useQuery({ query: GET_USERS })n  const { data, fetching, error } = resultnn  if (fetching) return <div>読み込み中...</div>n  if (error) return <div>エラー: {error.message}</div>nn  return (n    <ul>n      {/* user は GetUsersQuery['users'][number] 型として推論 */}n      {data?.users.map(user => (n        <li key={user.id}>n          {user.name} ({user.email})n        </li>n      ))}n    </ul>n  )n}

npm install -D @graphql-codegen/typescript-resolvers

// codegen.ts（サーバー設定）nimport type { CodegenConfig } from '@graphql-codegen/cli'nnconst config: CodegenConfig = {n  schema: './schema.graphql',n  generates: {n    // サーバー用の型生成n    './src/generated/resolvers.ts': {n      plugins: ['typescript', 'typescript-resolvers'],n      config: {n        contextType: '../types/context#GraphQLContext',  // コンテキスト型n        mappers: {n          // DB モデルとGraphQL型のマッピングn          User: '../models/user#UserModel',n          Post: '../models/post#PostModel',n        },n        scalars: {n          DateTime: 'Date',n        }n      }n    }n  }n}nnexport default config

// src/types/context.tsnimport { PrismaClient } from '@prisma/client'nimport { User as UserModel } from '@prisma/client'nnexport interface GraphQLContext {n  prisma: PrismaClientn  currentUser: UserModel | nulln}

// src/resolvers/userResolver.tsnimport { Resolvers } from '../generated/resolvers'nimport { GraphQLContext } from '../types/context'nn// Resolvers 型を使うとリゾルバーの引数・戻り値が型チェックされるnexport const userResolvers: Resolvers<GraphQLContext> = {n  Query: {n    // parent: unknown, args: { id: string }, context: GraphQLContextn    user: async (_parent, { id }, { prisma }) => {n      // prisma.user.findUnique の戻り値が User | nulln      return prisma.user.findUnique({ where: { id } })n    },n    users: async (_parent, _args, { prisma }) => {n      return prisma.user.findMany()n    },n  },nn  Mutation: {n    createUser: async (_parent, { input }, { prisma, currentUser }) => {n      // 認証チェックn      if (!currentUser) throw new Error('認証が必要です')nn      // input の型は CreateUserInput として推論されるn      return prisma.user.create({ data: input })n    },n  },nn  User: {n    // フィールドリゾルバー（関連データの解決）n    posts: async (parent, _args, { prisma }) => {n      // parent は UserModel 型として推論されるn      return prisma.post.findMany({ where: { authorId: parent.id } })n    },n  },n}

// src/app/users/page.tsx（Server Component）n// Apollo Client は RSC 非対応なので直接 fetch を使うnimport { GetUsersDocument, GetUsersQuery } from '@/generated/graphql'nimport { print } from 'graphql'  // DocumentNode を文字列に変換nnasync function fetchGraphQL<T, V extends Record<string, unknown>>(n  query: ReturnType<typeof print> | string,n  variables?: V,n  options?: RequestInitn): Promise<T> {n  const response = await fetch(n    process.env.GRAPHQL_ENDPOINT ?? 'http://localhost:4000/graphql',n    {n      method: 'POST',n      headers: { 'Content-Type': 'application/json' },n      body: JSON.stringify({ query, variables }),n      next: { revalidate: 60 },  // ISR: 60秒でキャッシュ更新n      ...options,n    }n  )nn  if (!response.ok) throw new Error(`GraphQL fetch failed: ${response.status}`)n  const { data, errors } = await response.json() as { data: T; errors?: unknown[] }n  if (errors) throw new Error(JSON.stringify(errors))n  return datan}nnexport default async function UsersPage() {n  // GetUsersQuery 型で型安全にデータを取得n  const data = await fetchGraphQL<GetUsersQuery, Record<string, never>>(n    print(GetUsersDocument)n  )nn  return (n    <ul>n      {data.users.map(user => (n        <li key={user.id}>{user.name}</li>n      ))}n    </ul>n  )n}

// src/components/providers/ApolloProvider.tsx（'use client'）n'use client'nnimport { ApolloClient, ApolloProvider, InMemoryCache } from '@apollo/client'nimport { ReactNode, useMemo } from 'react'nnexport function ApolloClientProvider({ children }: { children: ReactNode }) {n  const client = useMemo(n    () =>n      new ApolloClient({n        uri: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT,n        cache: new InMemoryCache(),n      }),n    []n  )nn  return <ApolloProvider client={client}>{children}</ApolloProvider>n}nn// src/app/layout.tsx（Server Component）nimport { ApolloClientProvider } from '@/components/providers/ApolloProvider'nnexport default function RootLayout({ children }: { children: React.ReactNode }) {n  return (n    <html>n      <body>n        <ApolloClientProvider>{children}</ApolloClientProvider>n      </body>n    </html>n  )n}

// src/types/graphqlError.tsnimport { GraphQLError } from 'graphql'nimport { ApolloError } from '@apollo/client'nn// GraphQL エラーコードの型定義ntype ErrorCode =n  | 'UNAUTHENTICATED'n  | 'FORBIDDEN'n  | 'NOT_FOUND'n  | 'BAD_USER_INPUT'n  | 'INTERNAL_SERVER_ERROR'nninterface GraphQLErrorExtensions {n  code: ErrorCoden  field?: string  // バリデーションエラーの場合n}nn// カスタムエラー型ninterface TypedGraphQLError extends GraphQLError {n  extensions: GraphQLErrorExtensionsn}nn// ApolloError からエラーコードを取得するユーティリティnexport function getErrorCode(error: ApolloError): ErrorCode | null {n  const gqlError = error.graphQLErrors[0] as TypedGraphQLError | undefinedn  return gqlError?.extensions.code ?? nulln}nn// 使用例nfunction handleMutationError(error: ApolloError) {n  const code = getErrorCode(error)n  switch (code) {n    case 'UNAUTHENTICATED':n      // ログインページにリダイレクトn      window.location.href = '/login'n      breakn    case 'FORBIDDEN':n      alert('この操作を行う権限がありません')n      breakn    case 'BAD_USER_INPUT':n      alert('入力内容を確認してください')n      breakn    default:n      alert('エラーが発生しました: ' + error.message)n  }n}

# Cursor-based pagination（推奨）ntype PageInfo {n  hasNextPage: Boolean!n  hasPreviousPage: Boolean!n  startCursor: Stringn  endCursor: Stringn}nntype UserEdge {n  node: User!n  cursor: String!n}nntype UserConnection {n  edges: [UserEdge!]!n  pageInfo: PageInfo!n  totalCount: Int!n}nntype Query {n  users(first: Int, after: String, last: Int, before: String): UserConnection!n}

// ページネーションクエリの型安全な使用nconst GET_USERS_PAGINATED = graphql(`n  query GetUsersPaginated($first: Int!, $after: String) {n    users(first: $first, after: $after) {n      edges {n        node {n          idn          namen          emailn        }n        cursorn      }n      pageInfo {n        hasNextPagen        endCursorn      }n      totalCountn    }n  }n`)nnfunction UserListPaginated() {n  const { data, fetchMore } = useQuery(GET_USERS_PAGINATED, {n    variables: { first: 10 },n  })nn  function loadMore() {n    if (!data?.users.pageInfo.hasNextPage) returnnn    fetchMore({n      variables: {n        after: data.users.pageInfo.endCursor,n      },n      updateQuery(prev, { fetchMoreResult }) {n        return {n          users: {n            ...fetchMoreResult.users,n            edges: [n              ...prev.users.edges,n              ...fetchMoreResult.users.edges,n            ],n          },n        }n      },n    })n  }nn  return (n    <div>n      {data?.users.edges.map(({ node }) => (n        <div key={node.id}>{node.name}</div>n      ))}n      {data?.users.pageInfo.hasNextPage && (n        <button onClick={loadMore}>もっと見る</button>n      )}n    </div>n  )n}

// Apollo Client のキャッシュを型安全に更新nimport { useApolloClient } from '@apollo/client'nimport { GetUsersDocument, GetUsersQuery, User } from '@/generated/graphql'nnfunction useAddUserToCache() {n  const client = useApolloClient()nn  return (newUser: User) => {n    // readQuery: キャッシュから型安全に読み取るn    const existing = client.readQuery<GetUsersQuery>({n      query: GetUsersDocument,n    })nn    if (!existing) returnnn    // writeQuery: キャッシュに型安全に書き込むn    client.writeQuery<GetUsersQuery>({n      query: GetUsersDocument,n      data: {n        users: [...existing.users, newUser],n      },n    })n  }n}

// Optimistic UI: 結果を楽観的に即座に表示するnconst [deleteUser] = useMutation(DELETE_USER, {n  optimisticResponse: ({ id }) => ({n    __typename: 'Mutation' as const,n    deleteUser: {n      __typename: 'User' as const,n      id,n    },n  }),n  update(cache, { data }) {n    if (!data?.deleteUser) returnn    // キャッシュから削除n    cache.evict({ id: cache.identify(data.deleteUser) })n    cache.gc()  // ガベージコレクションn  }n})