97 GraphQL Code Generator dan Otomatisasi Skema: Mempercepat Pengembangan API Modern

GraphQL kini semakin menjadi standar de facto dalam pengembangan API modern. Ia menawarkan query yang lebih fleksibel dibandingkan REST dan memungkinkan front-end serta back-end berkolaborasi lebih efektif. Namun, maintainability dan scalability dari skema GraphQL bisa menjadi tantangan tersendiri, apalagi ketika jumlah tipe, query, mutation, dan resolver makin bertambah.

Dalam artikel ini, saya ingin membahas salah satu tools yang sangat berharga untuk menunjang workflow pengembangan GraphQL, yaitu GraphQL Code Generator. Kita juga akan melihat bagaimana kode generator dapat membantu otomatisasi, mengurangi boilerplate, meningkatkan tipe safety, dan mempercepat time-to-market melalui contoh nyata dan diagram alur proses.

Disclaimer: Judul “97 GraphQL Code Generator” di sini mengacu pada versi dan variasi tools, bukan berarti ada 97 tools berbeda. Fokus bahasan utama pada tool GraphQL Code Generator yang sangat populer di ekosistem GraphQL.

Problematika Pengembangan Skema GraphQL

Saat kita membangun API GraphQL untuk sebuah layanan real-world, gambaran proses seringkali terlihat seperti ini:

flowchart TD
    A[Tulis skema GraphQL] --> B[Tulis resolver (manual)]
    B --> C[Test query]
    C --> D[Perbaiki skema & resolver jika perlu]

Setiap perubahan skema sering mengharuskan engineer untuk memperbarui resolver, typings TypeScript, ataupun generate documentation secara manual. Hal ini rawan terjadi inkonsistensi. Misal, ada perubahan pada skema (type User { ... }), engineer lupa update resolver dan tipe terkait, menyebabkan runtime error.

Solusi: Otomatisasi dengan GraphQL Code Generator

GraphQL Code Generator (@graphql-codegen/cli) hadir untuk memecahkan masalah ini.

Apa Itu GraphQL Code Generator?

Sederhananya, GraphQL Code Generator adalah tool open-source yang dapat men-generate kode statis berdasarkan skema GraphQL dan operasi (query/mutation) yang kita buat. Outputnya bisa berupa TypeScript typings, resolvers skeleton, React hooks, hingga dokumentasi API.

Keuntungan utama:

• Tipe Safety: Tidak ada lagi mistype property saat akses response.
• Mengurangi Boilerplate: Banyak kode yang otomatis di-generate, lebih sedikit copy-paste manual.
• Konsistensi: Skema, kode client, dan resolver selalu sinkron.
• Produktivitas: Waktu develop fitur baru jadi lebih singkat.

Studi Kasus: Generate TypeScript Types & React Hooks

Mari kita coba mensimulasikan project sederhana.

Skema GraphQL

Misal kita punya skema berikut (misal di file schema.graphql):

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  users: [User!]!
  user(id: ID!): User
}

Query GraphQL untuk Frontend (src/queries/getUsers.graphql)

query GetUsers {
  users {
    id
    name
    email
  }
}

Instalasi GraphQL Code Generator

Install dependensi di project berbasis Node.js:

npm install @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo --save-dev

Atau via Yarn:

yarn add @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo --dev

Konfigurasi: codegen.yml

Buat file config codegen.yml:

schema: ./schema.graphql
documents: ./src/queries/**/*.graphql
generates:
  ./src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

Proses Autogen: Workflow Diagram

sequenceDiagram
    autonumber
    User->>CodeGenCLI: run `graphql-codegen`
    CodeGenCLI->>Schema: Baca file schema.graphql
    CodeGenCLI->>Documents: Baca file query .graphql
    CodeGenCLI->>TypeScriptPlugin: Generate typings dari schema
    CodeGenCLI->>ReactApolloPlugin: Generate custom React hooks
    CodeGenCLI->>User: Output file src/generated/graphql.tsx

Jalankan Generator

npx graphql-codegen

Setelah dijalankan, kita akan mendapatkan file hasil autogenerate, misal src/generated/graphql.tsx.

Contoh Output yang Dihasilkan

Typings Otomatis

export type User = {
  __typename?: 'User';
  id: string;
  name: string;
  email: string;
};

export type GetUsersQuery = {
  users: Array<User>;
};

React Hook Otomatis

export function useGetUsersQuery(baseOptions?: Apollo.QueryHookOptions<GetUsersQuery>) {
  return Apollo.useQuery<GetUsersQuery, GetUsersQueryVariables>(GetUsersDocument, baseOptions);
}

Efeknya:
Frontend dev kini tinggal pakai useGetUsersQuery(), dapat autocomplete dan type safety penuh. Tidak perlu lagi menulis manual tipe response dan error prone.

Tabel Value Comparison

Otomatisasi Skema untuk Server (Backend)

Selain di side client, GraphQL Code Generator dapat membantu backend engineer generate skeleton untuk resolvers, misal plugin typescript-resolvers:

  ./src/generated/resolvers-types.ts:
    plugins:
      - typescript
      - typescript-resolvers

Outputnya:
Setiap perubahan di skema otomatis update interface di TypeScript. Misal:

export interface QueryResolvers<ContextType = any> {
  users: Resolver<Array<User>, {}, ContextType>;
  user: Resolver<User, { id: string }, ContextType>;
}

Resolusi error akibat mismatch return type dari resolver bisa dikurangi drastis! Resolver juga auto ter-typi-ng-kan; mengurangi bug runtime.

Skema Otomatisasi pada Real World Project

Kebanyakan tim engineering di unicorn/startup kini menggunakan pipelines seperti berikut:

flowchart TD
    Dev[Update schema.graphql] --> CI[CI/CD Pipeline]
    CI -->|auto-run| Codegen[GraphQL Codegen]
    Codegen --> Commit[Update commit typings]
    Commit --> Deploy[Deploy]

Dengan pola ini, semua schema dan code base tetap up-to-date secara otomatis, tidak mengganggu flow pengembangan.

Kesimpulan

GraphQL Code Generator adalah salah satu tool esensial bagi engineer yang membangun API modern. Ia menghadirkan otomatisasi dalam generate types, hooks, resolver skeleton hingga dokumentasi, sehingga kita bisa:

• Meningkatkan kecepatan pengembangan
• Mengurangi human error
• Menjamin konsistensi antara client/server

Jangan takut mencoba! Dalam tim besar, otomasi skema tidak hanya meningkatkan kualitas kode, tapi juga membangun budaya engineering yang sehat.

Apakah kamu sudah menggunakan codegen di project GraphQL-mu? Bagikan pengalaman atau kendala yang kamu jumpai di kolom komentar!