Belajar Gatsby - Architecture & Design Patterns

#Pendahuluan

Seiring situs bertumbuh, arsitektur yang baik lebih berharga daripada fitur baru. Keputusan tentang struktur folder, cara membagi komponen, dan pola berbagi kode menentukan apakah project tetap mudah dipahami oleh tim baru.

Episode 18 membahas struktur project untuk Gatsby yang scalable, component-driven design dan content modeling, pola shared components, hooks, dan utility, serta strategi maintainability dan kolaborasi.

#Struktur Project untuk Situs yang Scalable

#Organisasi Berdasarkan Domain

Folder src sebaiknya dikelompokkan berdasarkan fungsi, bukan semata tipe file. Struktur berikut memisahkan page, template, komponen, dan hook dengan tanggung jawab yang jelas:

src/
  pages/
  templates/
  components/
    layout/
    ui/
  hooks/
  utils/
  data/
  styles/

src/pages berisi routing file-based, src/templates berisi template untuk halaman yang dibuat secara programatik lewat createPage, sementara src/components menampung komponen yang dipakai ulang.

Untuk project yang besar, folder komponen bisa dipisah lagi per fitur — misalnya components/blog/ dan components/checkout/. Pemisahan berdasarkan fitur membuat kode yang berubah bersama juga berada bersama, sehingga tim yang mengerjakan fitur berbeda jarang saling bersinggungan di file yang sama. Struktur ini juga memudahkan code review: perubahan di satu fitur terlihat jelas tanpa menyentuh folder milik fitur lain.

#Kolokasi File Terkait

Letakkan file yang berubah bersama-sama: style, test, dan hook dari sebuah komponen diletakkan di folder komponen itu. Kolokasi memperpendek jarak pencarian dan membuat komponen menjadi unit yang mandiri. Saat komponen dihapus, seluruh turunannya ikut terhapus tanpa meninggalkan artefak yang mengambang. Aturan sederhananya: jika dua file selalu berubah bersama, letakkan keduanya bersebelahan.

#Component-Driven Design dan Content Modeling

#Komposisi Komponen

Rancang komponen dari yang kecil lalu disusun menjadi lebih besar. Halaman diturunkan dari section, section dari card, dan card dari elemen presentasional. Konsistensi ini membuat perubahan desain cukup dilakukan di satu level. Komponen yang terlalu besar menandakan ada lapisan komposisi yang hilang — pecah menjadi bagian yang lebih kecil dengan tanggung jawab tunggal.

#Content Modeling

Jenis konten di model data harus sesuai dengan kebutuhan halaman. Saat mendefinisikan skema GraphQL di Gatsby, pastikan field yang sering dipakai bersama ditarik ke level yang sama sehingga query di template tetap sederhana dan tidak menduplikasi logika transformasi. Model konten yang baik adalah model yang bisa diprediksi: siapa pun yang membaca schema langsung paham data apa yang tersedia tanpa menebak. Perubahan model di CMS lebih mahal daripada perubahan komponen, jadi pikirkan matang sebelum menambah field baru. Mulailah dari model yang paling kecil yang memenuhi kebutuhan halaman, lalu kembangkan saat kebutuhan benar-benar muncul.

#Shared Components, Hooks, dan Utility Patterns

#Custom Hooks untuk Logika Berulang

Logika yang dipakai banyak komponen — membaca metadata situs, mengakses data query — dipindah ke custom hook. Contoh membaca metadata situs:

Hook useSiteMetadata

import { useStaticQuery, graphql } from "gatsby"
 
export const useSiteMetadata = () => {
  const data = useStaticQuery(graphql`
    query SiteMetadata {
      site {
        siteMetadata {
          title
          description
        }
      }
    }
  `)
 
  return data.site.siteMetadata
}

useSiteMetadata mengemas query useStaticQuery sehingga komponen konsumen cukup memanggil satu hook tanpa menulis query berulang kali. Konvensi penamaan use di awal wajib dipenuhi agar React mengenali hook dan menjalankan aturan hook dengan benar.

Hook dapat diuji seperti fungsi biasa — bungkus dalam komponen kecil lalu assert hasilnya. Pola ini menjaga aturan React tetap terpenuhi sambil memastikan logika tetap benar. Letakkan pengujian hook di folder yang sama dengan hook-nya agar tetap kolokasi dan mudah ditemukan.

#Utility Functions Murni

Fungsi transformasi data — format tanggal, pembuatan slug, filter — dipisahkan ke src/utils sebagai fungsi murni. Fungsi murni mudah diuji karena menerima input dan mengembalikan output tanpa efek samping. Jika sebuah fungsi mulai membaca localStorage atau menulis ke DOM, pindahkan tanggung jawab itu ke hook atau komponen. Buat penamaan fungsi deskriptif sehingga pemakaiannya bisa ditebak tanpa membaca implementasi.

#Maintainability dan Kolaborasi

#Konvensi dan Typing

Tetapkan konvensi penamaan komponen, event handler, dan CSS sebelum tim mulai menulis kode. Penggunaan TypeScript menambahkan lapisan keamanan: props yang salah ketik akan tertangkap di waktu compile, bukan di runtime. Dokumentasikan keputusan arsitektur di README singkat agar tim baru tidak menebak ulang.

Sepakati juga tooling tim — formatter, linter, dan test runner — dan komit konfigurasinya ke repositori. Dengan begitu setiap anggota tim mendapat perilaku yang sama tanpa konfigurasi manual. Konfigurasi yang disepakati juga mengurangi noise di pull request yang seharusnya fokus pada logika perubahan.

#Dokumentasi dan Onboarding

Sertakan README yang menjelaskan cara menjalankan project, struktur folder, dan konvensi yang berlaku. Dokumentasi yang baik mempercepat onboarding anggota tim baru dan mengurangi tanya-jawab berulang. Perbarui dokumentasi di pull request yang mengubah alur kerja, bukan ditunda sampai akhir sprint. Jaga dokumentasi tetap pendek dan fokus pada hal yang sering ditanyakan.

#Review dan Refactoring Terus-Menerus

Jaga kebiasaan refactoring kecil setiap menambah fitur, bukan menunggu utang teknis menumpuk. Pull request yang kecil dan fokus lebih mudah direview dan lebih sedikit menimbulkan konflik dibanding perubahan raksasa. Jadikan refactoring bagian dari definisi selesai, bukan pekerjaan terpisah yang selalu ditunda.

#Penutup

Inti yang harus dibawa pulang:

• Kelompokkan folder src berdasarkan fungsi dan domain.
• Kolokasi style, test, dan hook bersama komponennya.
• Susun halaman lewat komposisi komponen dari kecil ke besar.
• Custom hooks mengemas query dan logika yang dipakai berulang.
• Fungsi murni di src/utils mudah diuji.
• Refactoring kecil dan review berkala menjaga kualitas kode.

Di episode 19 selanjutnya kita akan membahas tooling modern dan build automation — Gatsby CLI, dukungan TypeScript, pipeline CI/CD, serta linting, formatting, dan pre-commit hooks.