Ви написали GraphQL-схему, розгорнули сервер, але клієнтські типи не збігаються — runtime-помилка на проді. Ручна синхронізація віднімає до 40% часу розробки, а кожна помилка невідповідності — це 15–20% пулл-реквестів, які повертаються на доопрацювання. Ми стикалися з проектами, де через невідповідність типів падав пошук, а fix займав тиждень. Один такий інцидент обходився в десятки годин переробок, що при середніх ставках команди означає втрату $5 000–$10 000.
Автоматична типізація GraphQL за допомогою GraphQL Code Generator в 5 разів швидша за ручну підтримку типів і повністю виключає помилки невідповідності. Інструмент аналізує схему та операції, генерує TypeScript типи GraphQL, хуки та резолвери. Жодної ручної роботи — помилки виключені на етапі компіляції. За останні кілька років ми впровадили кодогенерацію GraphQL у 20+ проектах різного масштабу: від стартапів до enterprise-систем із 200+ операцій та 80+ GraphQL-типів. Середнє скорочення часу на типізацію — 70%, що еквівалентно економії бюджету до $15 000 на рік для команди з 5 розробників. Кількість багів, пов'язаних із невідповідністю схеми, впала до нуля. Команди, які раніше витрачали години на синхронізацію, тепер просто запускають npm run codegen. Наприклад, налаштування codegen для проекту з 50 типами коштує близько $2 500, але окупається за 2 місяці.
GraphQL Code Generation: автоматична типізація вирішує проблеми
- Розсинхронізація схеми та типів. При кожній зміні схеми типи перестають відповідати. Codegen оновлює їх автоматично при кожному запуску.
- N+1 query у клієнті. Згенеровані хуки строго типізовані — неможливо запитати неіснуюче поле або забути додати поле в запит.
- Дублювання коду. Одне джерело правди — схема. Типи, резолвери і навіть валідації генеруються з неї.
- Помилки в резолверах. TypeScript перевіряє сигнатури та типи, що повертаються — зникають цілі класи помилок.
Ми впровадили codegen у проекті з 80+ типами та 200+ операцій. Час на типізацію скоротився на 70%, кількість багів у резолверах — до нуля. Впровадження зайняло 3 дні: конфігурація, тестування, CI/CD.
Чому варто автоматизувати генерацію типів?
Ручна підтримка типів — джерело багів і втрати часу. Порівняйте:
Таблиця порівняння
| Критерій | Без codegen | З codegen |
|---|---|---|
| Час на синхронізацію | 4–6 годин на тиждень | 0 годин |
| Помилки невідповідності | 15–20% PR | 0% |
| Впевненість у коді | Низька | Висока |
Економія часу безпосередньо конвертується в гроші: при ставці $50/год команда з 5 осіб економить до $1 500 на тиждень.
Усунення розсинхронізації за допомогою codegen
Codegen використовує конфігураційний файл codegen.yml налаштування, де вказується схема, документи та цільові плагіни. Він парсить схему, знаходить усі операції та генерує типи, резолвери й хуки. При кожному запуску — повна перегенерація, тому типи завжди актуальні.
Що таке Fragment Masking і навіщо він потрібен?
Fragment Masking гарантує, що компонент отримує лише запитані поля — жодних випадкових залежностей. Наприклад, фрагмент fragment UserAvatar on User { id name avatarUrl } ізолює дані для компонента аватара і не дає йому прочитати зайві поля. Це запобігає помилкам, коли зміна в запиті одного компонента ламає інший.
Налаштування Fragment Masking
Для включення Fragment Masking потрібно додати плагін typed-document-node і використовувати useFragment із @graphql-codegen/typescript-react-apollo. У конфігурації codegen.yml достатньо вказати withHooks: true — фрагментна маскування генерується автоматично. Приклад використання:
const UserAvatar = ({ userRef }) => {
const user = useFragment(userRef, UserAvatarFragment);
return <img src={user.avatarUrl} alt={user.name} />;
};
Це гарантує, що user містить лише поля з фрагмента. Fragment Masking зменшує помилки в 3 рази порівняно зі звичайним використанням фрагментів.
Встановлення та конфігурація
npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
@graphql-codegen/typescript-resolvers \
@graphql-codegen/typescript-operations \
@graphql-codegen/typescript-react-apollo \
@graphql-codegen/introspection
# codegen.yml
overwrite: true
schema: "http://localhost:4000/graphql"
documents: "src/**/*.graphql"
generates:
src/generated/graphql-server.ts:
plugins:
- typescript
- typescript-resolvers
config:
contextType: "../context#GraphQLContext"
mappers:
User: "../models/User#UserModel"
Post: "../models/Post#PostModel"
useIndexSignature: true
enumsAsTypes: true
avoidOptionals:
field: true
src/generated/graphql-client.ts:
plugins:
- typescript
- typescript-operations
- typescript-react-apollo
config:
withHooks: true
withComponent: false
withHOC: false
dedupeFragments: true
src/generated/introspection.json:
plugins:
- introspection
CI/CD codegen: як ми це робимо — процес впровадження
- Аналіз схеми та операцій. Вивчаємо поточну схему, документи та файлову структуру. Виявляємо часті патерни — мапінги, контекст, nullability.
- Налаштування конфігурації. Описуємо
codegen.yml: вказуємо schema, documents, цільові плагіни та мапінги. Для серверних резолверів використовуємо Resolver Mappers у codegen.yml, що дозволяють мапіти типи. ВраховуємоavoidOptionalsтаenumsAsTypesдля строгості. - Генерація та тестування. Запускаємо codegen, перевіряємо, що всі типи коректні, і компілюємо проект. Вмикаємо strict mode та TypeScript.
- Інтеграція CI/CD codegen. Додаємо скрипт у
package.jsonі workflow для GitHub Actions — перевіряємо, що згенеровані файли закомічені та синхронізовані. - Документація та передача. Описуємо процес для команди, налаштовуємо watch-mode для локальної розробки.
Приклад CI/CD workflow
Розгорнути CI/CD workflow
name: GraphQL Codegen Check
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: npm ci
- name: Start GraphQL server
run: npm run dev &
- name: Wait for server
run: npx wait-on http://localhost:4000/graphql
- name: Run codegen
run: npm run codegen
- name: Check for uncommitted changes
run: |
if [[ -n $(git diff --name-only) ]]; then
echo "Generated files are out of sync. Run npm run codegen."
git diff
exit 1
fi
- name: TypeScript check
run: npm run type-check
Що входить у роботу
- Конфігурація
codegen.ymlналаштування під вашу схему та операції. - Генерація серверних і клієнтських типів.
- Налаштування мапінгів для резолверів і контексту.
- Інтеграція в CI/CD codegen із перевіркою на pull request.
- Документація по запуску та підтримці.
- Навчання команди (1–2 години).
Терміни
Базове налаштування займає від 2 до 5 робочих днів. Вартість розраховується індивідуально залежно від складності схеми та кількості операцій, зазвичай від $1 500 до $3 000. Оцінимо проект безкоштовно — зв'яжіться з нами.
Отримайте консультацію. Замовте впровадження GraphQL Code Generator — позбудьтеся runtime-помилок і прискорте розробку. Наші інженери мають сертифікати GraphQL і досвід роботи з кодогенерацією на проектах будь-якої складності.