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.

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]

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):

 1type User {
 2  id: ID!
 3  name: String!
 4  email: String!
 5}
 6
 7type Query {
 8  users: [User!]!
 9  user(id: ID!): User
10}

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

1query GetUsers {
2  users {
3    id
4    name
5    email
6  }
7}

Instalasi GraphQL Code Generator

Install dependensi di project berbasis Node.js:

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

Atau via Yarn:

1yarn 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:

1schema: ./schema.graphql
2documents: ./src/queries/**/*.graphql
3generates:
4  ./src/generated/graphql.tsx:
5    plugins:
6      - typescript
7      - typescript-operations
8      - 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

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

1npx graphql-codegen

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

Contoh Output yang Dihasilkan

Typings Otomatis

 1export type User = {
 2  __typename?: 'User';
 3  id: string;
 4  name: string;
 5  email: string;
 6};
 7
 8export type GetUsersQuery = {
 9  users: Array<User>;
10};

React Hook Otomatis

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

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:

1  ./src/generated/resolvers-types.ts:
2    plugins:
3      - typescript
4      - typescript-resolvers

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

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

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]

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!