2nd/10_Wiki/Topics/Frontend/Codegen.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-codegen	Codegen (GraphQL, OpenAPI, Schema-driven)	10_Wiki/Topics	verified	self	Code Generation GraphQL Codegen OpenAPI Codegen	none	A	0.9	applied	codegen graphql openapi typescript tooling		2026-05-10	pending	language framework TypeScript GraphQL Code Generator / openapi-typescript

Codegen (Schema-driven Code Generation)

매 한 줄

"매 schema 가 single source of truth". Codegen 은 GraphQL/OpenAPI/Protobuf schema 에서 type 과 client code 를 자동 생성 — 매 manual sync 의 X, drift 의 zero, refactor 매 compile-time safe.

매 핵심

매 주요 도구 (2026)

• GraphQL: @graphql-codegen/cli (client preset), gql.tada (zero-config inline).
• OpenAPI: openapi-typescript (types), openapi-fetch (typed client), orval (React Query hooks).
• gRPC/Protobuf: bufbuild/protobuf-es, connect-es.
• DB schema: kysely-codegen, drizzle-kit, Prisma.

매 출력 종류

• Type definitions only (lightweight).
• Typed client (operations + types).
• Hooks/composables (React Query, SWR, urql).
• Server stubs (resolvers, controllers).

매 watch vs build-time

• Dev: watch mode → 매 save 시 regen.
• CI: --check 로 매 schema/code drift 검출.
• Pre-commit: 매 generated files 매 staged 보장.

💻 패턴

GraphQL client preset (@graphql-codegen/cli)

# codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'https://api.example.com/graphql',
  documents: ['src/**/*.{ts,tsx}'],
  generates: {
    'src/gql/': {
      preset: 'client',
      config: { useTypeImports: true, scalars: { DateTime: 'string' } },
    },
  },
};
export default config;

Using generated graphql() (typed documents)

import { graphql } from '@/gql';
import { useQuery } from '@tanstack/react-query';

const FlightSearch = graphql(`
  query FlightSearch($from: String!, $to: String!) {
    flights(from: $from, to: $to) { id price airline }
  }
`);

export function useFlights(vars: { from: string; to: string }) {
  return useQuery({
    queryKey: ['flights', vars],
    queryFn: () => request('/graphql', FlightSearch, vars),
  });
}

gql.tada (zero-config alternative)

import { graphql } from 'gql.tada';

const Query = graphql(`
  query Me { me { id email } }
`);
// 매 inferred 매 fully typed — no codegen step

openapi-typescript + openapi-fetch

npx openapi-typescript ./openapi.yaml -o ./src/api/schema.ts

import createClient from 'openapi-fetch';
import type { paths } from './api/schema';

const api = createClient<paths>({ baseUrl: 'https://api.example.com' });

const { data, error } = await api.GET('/users/{id}', {
  params: { path: { id: '42' } },
});
// data 매 매 fully typed

orval — React Query hooks from OpenAPI

// orval.config.ts
export default {
  api: {
    input: './openapi.yaml',
    output: {
      target: './src/api/generated.ts',
      client: 'react-query',
      mode: 'tags-split',
    },
  },
};

Drizzle Kit — DB schema introspection

drizzle-kit introspect:pg --connectionString=$DATABASE_URL --out=./src/db

CI drift check

# .github/workflows/codegen-check.yml
- run: pnpm codegen
- run: git diff --exit-code src/gql src/api

Husky pre-commit

# .husky/pre-commit
pnpm codegen && git add src/gql src/api

매 결정 기준

상황	도구
GraphQL + React/Vue	@graphql-codegen client preset
GraphQL + want zero step	gql.tada
OpenAPI types only	openapi-typescript
OpenAPI + hooks	orval
DB-first	Drizzle / Prisma / Kysely codegen

기본값: GraphQL → client preset; REST → openapi-typescript + openapi-fetch.

🔗 Graph

• 부모: Tooling · Type-Safety
• 변형: GraphQL · OpenAPI · gRPC
• 응용: React-Query · urql · Apollo-Client
• Adjacent: Schema-First-Design · Contract-Testing

🤖 LLM 활용

언제: schema-driven API integration / 매 type drift 매 painful 한 monorepo. 언제 X: 매 throwaway prototype, schema 매 unstable.

❌ 안티패턴

• Hand-writing GraphQL types: 매 drift 의 zero-day issue.
• Committing nothing then expecting safety: 매 generated files 매 commit + CI check 둘 다 필요.
• Running codegen only locally: 매 CI drift check 의 X 면 PR 매 깨짐.

🧪 검증 / 중복

• Verified (the-guild.dev / openapi-ts.dev / orval.dev official docs).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — codegen tools (GraphQL/OpenAPI) with patterns