Blog

Cara Menggunakan graphql-codegen: Panduan Pemula

Maurice Odida

Maurice Odida

20 June 2025

Cara Menggunakan graphql-codegen: Panduan Pemula

Dalam lanskap pengembangan web yang terus berkembang, GraphQL telah muncul sebagai alternatif yang kuat untuk API REST tradisional, menawarkan klien kemampuan untuk meminta data persis yang mereka butuhkan. Namun, fleksibilitas ini dapat memperkenalkan serangkaian tantangan baru, terutama dalam menjaga keamanan tipe (type safety) antara frontend dan backend. Di sinilah graphql-codegen berperan, sebuah alat revolusioner yang mengotomatiskan pembuatan kode bertipe dari skema GraphQL Anda, mempercepat alur kerja pengembangan Anda dan menghilangkan seluruh kelas kesalahan saat runtime.

Artikel ini akan menjadi panduan Anda untuk memahami dan menguasai graphql-codegen. Kita akan mulai dengan konsep fundamental, menelusuri contoh praktis langkah demi langkah tentang cara menyiapkan dan mengkonfigurasi alat ini, dan menjelajahi praktik terbaik untuk mengintegrasikannya ke dalam proyek Anda. Di akhir panduan ini, Anda akan siap memanfaatkan graphql-codegen untuk membangun aplikasi yang lebih kuat, mudah dipelihara, dan aman tipe.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Apa itu graphql-codegen dan Mengapa Anda Membutuhkannya?

Intinya, graphql-codegen adalah alat baris perintah yang memeriksa skema GraphQL Anda dan operasi GraphQL Anda (queries, mutations, dan subscriptions) serta menghasilkan kode dalam berbagai bahasa. Untuk tujuan panduan pemula ini, kita akan fokus pada kasus penggunaan yang paling populer: menghasilkan tipe dan hook TypeScript untuk aplikasi frontend.

Masalah utama yang dipecahkan oleh graphql-codegen adalah proses yang membosankan dan rentan kesalahan dalam menulis antarmuka TypeScript secara manual untuk struktur data API GraphQL Anda dan hasil dari kueri Anda. Tanpa itu, pengembang dibiarkan bekerja dengan data tanpa tipe (kehilangan manfaat TypeScript) atau menghabiskan banyak waktu untuk membuat dan memelihara tipe yang dapat dengan mudah menjadi usang seiring berkembangnya API.

Manfaat mengadopsi graphql-codegen sangat banyak:

Pendekatan ini sangat selaras dengan filosofi pengembangan "schema-first", di mana skema GraphQL berfungsi sebagai sumber kebenaran tunggal untuk API Anda.

Memulai: Pengaturan graphql-codegen Pertama Anda

Mari kita selami aspek praktis penggunaan graphql-codegen. Untuk tutorial ini, kita akan mengasumsikan Anda memiliki pemahaman dasar tentang GraphQL, TypeScript, dan telah menginstal Node.js serta manajer paket (seperti npm atau yarn).

Tujuan kita adalah menyiapkan graphql-codegen untuk aplikasi React sederhana yang menampilkan daftar posting blog.

Langkah 1: Inisialisasi Proyek dan Dependensi

Pertama, mari buat proyek React baru dengan TypeScript dan instal dependensi yang diperlukan.Bash

npx create-react-app my-blog --template typescript
cd my-blog
npm install @apollo/client graphql
npm install -D @graphql-codegen/cli @graphql-codegen/client-preset typescript

Berikut adalah rincian dependensi yang telah kita instal:

Langkah 2: Wizard Inisialisasi graphql-codegen

Cara termudah untuk memulai dengan graphql-codegen adalah dengan menggunakan wizard inisialisasinya. Jalankan perintah berikut di direktori root proyek Anda:Bash

npx graphql-codegen init

Wizard akan menanyakan serangkaian pertanyaan untuk membantu mengkonfigurasi proyek Anda. Berikut adalah set jawaban umum untuk skenario aplikasi blog kita:

Setelah menjawab pertanyaan-pertanyaan ini, wizard akan membuat file codegen.ts di root proyek Anda dan menambahkan skrip codegen ke package.json Anda.

Langkah 3: Memahami File Konfigurasi (codegen.ts)

File codegen.ts adalah inti dari pengaturan graphql-codegen Anda. Mari kita lihat versi sederhana dari apa yang dihasilkan wizard:TypeScript

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  overwrite: true,
  schema: "https://swapi-graphql.netlify.app/.netlify/functions/index",
  documents: "src/**/*.tsx",
  generates: {
    "src/gql/": {
      preset: "client",
      plugins: []
    }
  }
};

export default config;

Mari kita bedah opsi konfigurasi utama:

Langkah 4: Menulis Kueri GraphQL Pertama Anda

Sekarang graphql-codegen telah dikonfigurasi, mari kita tulis kueri GraphQL untuk mengambil posting blog kita. Buat file baru src/components/Posts.tsx:TypeScript

import { gql } from '../gql/gql';
import { useQuery } from '@apollo/client';

const GET_POSTS = gql(`
  query GetPosts {
    allFilms {
      films {
        id
        title
        director
        releaseDate
      }
    }
  }
`);

const Posts = () => {
  const { loading, error, data } = useQuery(GET_POSTS);

  if (loading) return <p>Memuat...</p>;
  if (error) return <p>Kesalahan :(</p>;

  return (
    <div>
      {data?.allFilms?.films?.map((film) => (
        <div key={film?.id}>
          <h2>{film?.title}</h2>
          <p>Sutradara: {film?.director}</p>
          <p>Tanggal Rilis: {film?.releaseDate}</p>
        </div>
      ))}
    </div>
  );
};

export default Posts;

Perhatikan bahwa kita mengimpor fungsi gql dari file src/gql/gql.ts yang dihasilkan. Ini adalah fungsi gql yang disediakan oleh client-preset dan inilah yang memungkinkan keajaiban inferensi tipe.

Langkah 5: Menjalankan graphql-codegen dan Melihat Keajaibannya

Sekarang, jalankan skrip codegen dari package.json Anda:Bash

npm run codegen

Perintah ini akan memeriksa skema, menemukan kueri GET_POSTS Anda, dan menghasilkan tipe TypeScript yang sesuai di direktori src/gql.

Jika Anda sekarang memeriksa objek data yang dikembalikan oleh hook useQuery di Posts.tsx, Anda akan melihat bahwa itu sepenuhnya bertipe! IDE Anda akan menyediakan autocompletion untuk data.allFilms.films, dan TypeScript akan memperingatkan Anda jika Anda mencoba mengakses bidang yang tidak ada dalam kueri.

Selami Lebih Dalam: Contoh Frontend Blog Praktis

Mari kita perluas contoh kita untuk memperkuat pemahaman Anda. Bayangkan blog kita memiliki skema yang lebih tradisional:GraphQL

type Author {
  id: ID!
  name: String!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: Author!
}

type Query {
  posts: [Post!]!
  post(id: ID!): Post
}

type Mutation {
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

Mari kita asumsikan skema ini berjalan di http://localhost:4000/graphql. Kita akan memperbarui codegen.ts kita sesuai dengan itu:TypeScript

// codegen.ts
// ...
schema: "http://localhost:4000/graphql",
// ...

Sekarang, mari kita buat komponen untuk menampilkan satu posting dan komponen lain untuk membuat posting baru.

Mengambil Satu PostingTypeScript

// src/components/Post.tsx
import { gql } from '../gql/gql';
import { useQuery } from '@apollo/client';
import { useParams } from 'react-router-dom';

const GET_POST = gql(`
  query GetPost($id: ID!) {
    post(id: $id) {
      id
      title
      content
      author {
        id
        name
      }
    }
  }
`);

const Post = () => {
  const { id } = useParams<{ id: string }>();
  const { loading, error, data } = useQuery(GET_POST, {
    variables: { id },
  });

  if (loading) return <p>Memuat...</p>;
  if (error) return <p>Kesalahan :(</p>;

  return (
    <div>
      <h2>{data?.post?.title}</h2>
      <p>Oleh {data?.post?.author?.name}</p>
      <p>{data?.post?.content}</p>
    </div>
  );
};

export default Post;

Setelah menjalankan npm run codegen, tipe untuk GetPostQuery dan variabelnya akan dihasilkan, memberikan keamanan tipe untuk hook useQuery dan hasilnya.

Membuat Posting BaruTypeScript

// src/components/CreatePost.tsx
import { gql } from '../gql/gql';
import { useMutation } from '@apollo/client';
import { useState } from 'react';

const CREATE_POST = gql(`
  mutation CreatePost($title: String!, $content: String!, $authorId: ID!) {
    createPost(title: $title, content: $content, authorId: $authorId) {
      id
    }
  }
`);

const CreatePost = () => {
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  const [createPost, { data, loading, error }] = useMutation(CREATE_POST);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    createPost({ variables: { title, content, authorId: '1' } }); // Mengasumsikan authorId '1' untuk kesederhanaan
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Judul"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
      />
      <textarea
        placeholder="Konten"
        value={content}
        onChange={(e) => setContent(e.target.value)}
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Membuat...' : 'Buat Posting'}
      </button>
      {error && <p>Kesalahan saat membuat posting: {error.message}</p>}
      {data && <p>Posting dibuat dengan ID: {data.createPost.id}</p>}
    </form>
  );
};

export default CreatePost;

Di sini, graphql-codegen menghasilkan tipe untuk CreatePostMutation dan variabelnya. Ini memastikan bahwa ketika Anda memanggil fungsi createPost, Anda meneruskan tipe yang benar untuk title, content, dan authorId.

Konsep Lanjutan dan Praktik Terbaik

Seiring Anda menjadi lebih nyaman dengan graphql-codegen, Anda akan menemukan fitur yang lebih canggih dan praktik terbaik:

Memecahkan Masalah Umum

Meskipun graphql-codegen adalah alat yang ampuh, Anda mungkin menemui beberapa masalah umum sebagai pemula:

Kesimpulan: Rangkullah Masa Depan yang Aman Tipe

graphql-codegen lebih dari sekadar alat pembuatan kode; ini adalah perubahan paradigma dalam cara kita membangun aplikasi dengan GraphQL. Dengan merangkul otomatisasi dan memanfaatkan kekuatan skema Anda, Anda dapat membuat basis kode yang lebih kuat, mudah dipelihara, dan menyenangkan untuk dikerjakan.

Tutorial ini telah memberi Anda dasar yang kuat untuk memulai dengan graphql-codegen. Kita telah membahas konsep inti, menelusuri contoh praktis, dan menyentuh praktik terbaik. Perjalanan tidak berakhir di sini. Ekosistem graphql-codegen sangat luas, dengan banyak koleksi plugin yang melayani berbagai kerangka kerja dan kasus penggunaan. Saya mendorong Anda untuk menjelajahi dokumentasi resmi, bereksperimen dengan plugin yang berbeda, dan menemukan bagaimana graphql-codegen dapat merevolusi alur kerja pengembangan GraphQL Anda. Selamat coding!

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh