GraphQL에서 TypeScript 정의로 변환 — Numio

@graphql-codegen/typescript로 GraphQL 스키마에서 TypeScript 타입을 생성하고, Document 패널의 operation에 대한 결과 타입과 변수 타입도 생성합니다. nullable 필드는 선택적 Maybe<T> 프로퍼티가 되고, non-null 리스트는 Array<T>가 됩니다.

codegen.yml 설정과 CLI 실행 없이 프런트엔드에서 쿼리가 반환하는 데이터에 타입을 지정합니다.

GraphQL Schema

Document

TypeScript

이럴 때 사용하세요

codegen.yml 설정과 CLI 실행 없이 프런트엔드에서 쿼리가 반환하는 데이터에 타입을 지정합니다.
스키마 변경(필드가 nullable이 되거나 enum 값이 추가됨)이 생성된 TypeScript에서 어떻게 보이는지 커밋 전에 확인합니다.

사용 방법

SDL(type, enum, interface, union, scalar 정의)을 GraphQL Schema 편집기에 붙여 넣습니다.
query, mutation, fragment를 Document 편집기에 넣거나, 스키마 타입만 필요하면 비워 둡니다. 스키마와 맞지 않는 document는 경고 주석과 함께 건너뜁니다.
생성된 타입을 복사합니다: User 같은 스키마 타입과, 이름 있는 operation마다 생성되는 GetUserQuery와 GetUserQueryVariables.

GraphQL 스키마 + document

# GraphQL Schema editor
type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  name: String
  tags: [String!]!
}

# Document editor
query GetUser($id: ID!) {
  user(id: $id) { id name }
}

TypeScript 타입

…
export type Query = {
  __typename?: "Query"
  user?: Maybe<User>
}

export type QueryUserArgs = {
  id: Scalars["ID"]["input"]
}

export type User = {
  __typename?: "User"
  id: Scalars["ID"]["output"]
  name?: Maybe<Scalars["String"]["output"]>
  tags: Array<Scalars["String"]["output"]>
}

export type GetUserQueryVariables = Exact<{
  id: Scalars["ID"]["input"]
}>

export type GetUserQuery = {
  __typename?: "Query"
  user?: { __typename?: "User"; id: string; name?: string | null } | null
}

세부 정보 및 제한 사항

출력은 고정된 헬퍼 타입(Maybe, InputMaybe, Exact, MakeOptional, Scalars 등)으로 시작하며, 위 예시에서는 '…'로 줄였습니다. Scalars는 각 스칼라를 input 타입과 output 타입으로 나눠 매핑합니다.

Date 같은 커스텀 스칼라는 any 타입이 됩니다. enum 값은 PascalCase 키를 가진 TypeScript enum이 됩니다(USER는 User = "USER").

생성은 브라우저 Web Worker에서 실행되며 아무것도 업로드되지 않습니다. 결과는 세미콜론 없이 Prettier로 포맷되며, 페이지에 codegen 설정 옵션은 없습니다.

FAQ

출력이 "// Document ignored"로 시작하는 이유는 무엇인가요?

Document 편집기 내용은 스키마에 대해 검증되며, 기본 예시는 username 같은 필드를 조회합니다. 검증에 실패해도 페이지는 스키마 타입을 생성하고 첫 번째 오류를 맨 위에 주석으로 넣습니다. operation을 수정하거나 Document 편집기를 비우세요.

nullable 필드는 어떤 타입이 되나요?

name: String 같은 nullable 필드는 name?: Maybe<Scalars["String"]["output"]>이 되며, Maybe<T>는 T | null입니다. operation 결과 타입에서는 name?: string | null로 인라인으로 작성됩니다.

쿼리 타입에는 선택한 필드만 포함되나요?

네. GetUserQuery에는 쿼리가 선택한 필드(여기서는 id와 name)만 들어가고 __typename은 선택적 프로퍼티입니다. 전체 User 타입은 별도로 생성됩니다.

사양 및 참고 자료

GraphQL Code Generator: typescript plugin