Belajar GraphQL - Type-Safe Development dengan GraphQL Code Generator

#Pendahuluan

TypeScript membuat JavaScript lebih aman, tetapi tanpa integrasi, tipe di GraphQL dan TypeScript bisa melenceng — schema bilang satu hal, kode bilang hal lain. Episode 23 menyatukan keduanya dengan GraphQL Code Generator.

Codegen membaca schema dan query kalian, lalu menghasilkan tipe TypeScript yang menjamin: kalau schema berubah, kode yang salah tipe langsung error saat compile. Kita akan membahas instalasi, konfigurasi, generasi tipe server dan client, serta integrasi ke workflow.

#GraphQL Code Generator

#Apa Itu Codegen

GraphQL Code Generator adalah tool yang mengubah schema GraphQL menjadi kode. Inputnya: schema (SDL, introspection, atau endpoint) dan dokumen (query, mutation, fragment). Outputnya: tipe TypeScript, hook React, dan banyak lagi lewat plugin.

npm install -D @graphql-codegen/cli @graphql-codegen/typescript

Manfaat utamanya satu kata: type safety. Jika schema menambah non-null atau menghapus field, kode client dan resolver yang usang langsung gagal kompilasi — bukan gagal di production.

#Configuration File

Buat codegen.yml:

schema: http://localhost:4000
documents: "src/**/*.graphql"
generates:
  src/generated/types.ts:
    plugins:
      - typescript
      - typescript-operations

Jalankan:

npx graphql-codegen

Perintah npx graphql-codegen menghasilkan file types.ts berisi semua tipe dari schema dan operasi. Setelah ini, jalankan mode watch saat development.

#TypeScript Generation

#Tipe dari Schema

Plugin typescript menghasilkan tipe untuk setiap tipe GraphQL. Misalnya schema:

type User {
  id: ID!
  username: String!
  posts: [Post!]!
}

menghasilkan:

Tipe hasil codegen

export type User = {
  __typename?: "User";
  id: Scalars["ID"]["output"];
  username: Scalars["String"]["output"];
  posts: Array<Post>;
};

Semua tipe object, input, dan enum dihasilkan otomatis. Perubahan schema langsung tercermin — tidak ada lagi ketidakcocokan manual.

#Type-Safe Resolvers

Untuk sisi server, plugin typescript-resolvers menghasilkan signature resolver yang typed, lengkap dengan context:

generates:
  src/generated/resolvers.ts:
    plugins:
      - typescript
      - typescript-resolvers
    config:
      contextType: ../context#GraphQLContext

Resolver typed

import { Resolvers } from "./generated/resolvers";
 
export const resolvers: Resolvers = {
  Query: {
    user: (_, args, ctx) => ctx.userRepo.findById(args.id),
  },
};

Jika resolver mengembalikan bentuk yang tidak cocok dengan schema, TypeScript langsung memperingatkan. contextType menghubungkan context GraphQL kalian sehingga ctx juga ter-typed.

#Client-Side Codegen

#Generating React Hooks

Plugin typescript-react-apollo menghasilkan hook useQuery dan useMutation yang typed untuk setiap operasi:

npm install -D @graphql-codegen/typescript-react-apollo

schema: http://localhost:4000
documents: "src/**/*.graphql"
generates:
  src/generated/hooks.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

Lalu di komponen:

Hook typed dari codegen

import { useGetUserQuery } from "../generated/hooks";
 
function Profile({ userId }: { userId: string }) {
  const { data, loading } = useGetUserQuery({
    variables: { id: userId },
  });
  return <p>{data?.user.username}</p>;
}

Hook ini menjamin variabel dan data query cocok dengan schema. Operasi yang memakai variabel salah tipe akan error saat compile — keunggulan yang mustahil didapat tanpa codegen.

#Workflow Integration

#Watch Mode dan Pre-commit

Agar tipe selalu sinkron, integrasikan codegen ke workflow:

{
  "scripts": {
    "codegen": "graphql-codegen",
    "codegen:watch": "graphql-codegen --watch"
  }
}

Jalankan npm run codegen:watch saat development agar tipe diperbarui otomatis setiap file berubah. Di production, jalankan codegen sebelum typecheck di CI, dan pasang di pre-commit hook (misalnya dengan Husky) agar kode dengan tipe basi tidak pernah ter-commit:

npx husky-init
echo "npm run codegen && git add src/generated" > .husky/pre-commit

#Menjaga Sync Schema

Untuk memastikan kode tidak tertinggal jauh dari schema, jalankan schema check sebelum merge (episode 32) dan biasakan men-generate ulang tipe setiap kali schema berubah. Kombinasi codegen, linting schema, dan CI menjadikan type safety sebagai budaya, bukan sekadar alat.

#Penutup

Inti yang harus dibawa pulang:

• GraphQL Code Generator mengubah schema dan operasi menjadi tipe TypeScript.
• Plugin typescript menghasilkan tipe schema; typescript-resolvers mengetik resolver dengan context.
• Plugin typescript-react-apollo menghasilkan hook query dan mutation yang typed.
• codegen.yml mendefinisikan schema, dokumen, dan output per plugin.
• Watch mode menjaga tipe sinkron saat development.
• Integrasikan codegen ke pre-commit dan CI untuk mencegah drift.

Di episode 24 selanjutnya kalian akan mempelajari monitoring, logging, dan observability — strategi logging terstruktur dengan Pino, setup Apollo Studio untuk query analytics, integrasi OpenTelemetry untuk distributed tracing, metrik Prometheus dan Grafana, hingga health checks. API kalian akan bisa diawasi penuh di production!