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

---
id: wiki-2026-0508-codegen
title: Codegen (GraphQL, OpenAPI, Schema-driven)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Code Generation, GraphQL Codegen, OpenAPI Codegen]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [codegen, graphql, openapi, typescript, tooling]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: 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)
```yaml
# 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)
```ts
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)
```ts
import { graphql } from 'gql.tada';

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

### openapi-typescript + openapi-fetch
```bash
npx openapi-typescript ./openapi.yaml -o ./src/api/schema.ts
```
```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
```ts
// 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
```bash
drizzle-kit introspect:pg --connectionString=$DATABASE_URL --out=./src/db
```

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

### Husky pre-commit
```sh
# .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
- 부모: [[Type-Safety]]
- 변형: [[OpenAPI]] · [[gRPC]]
- 응용: [[React-Query]]
- Adjacent: [[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 |