Belajar Gatsby - Configuration & Environment

#Pendahuluan

Seiring project membesar, konfigurasi dan pengelolaan environment menjadi penentu kelancaran. Gatsby menyediakan dua file konfigurasi utama plus sistem environment variables yang jelas aturannya.

Episode 8 membedah gatsby-config.js dan gatsby-node.js, konvensi environment variables Gatsby, peran source dan transformer plugins, kustomisasi schema, serta cara aman mengelola secret.

#gatsby-config.js dan gatsby-node.js

#Dua File dengan Peran Berbeda

• gatsby-config.js: konfigurasi deklaratif — siteMetadata, daftar plugins, dan flags.
• gatsby-node.js: logika imperatif — membuat halaman dengan createPages, memodifikasi node dengan onCreateNode, dan mengubah schema.

Keduanya berjalan di lingkungan Node.js saat build, jadi bisa memakai API Node apa pun dan seluruh process.env.

#Contoh Lifecycle di gatsby-node

gatsby-node.js mengekspor fungsi lifecycle. Salah satu yang paling sering dipakai:

createPages di gatsby-node

exports.createPages = async ({ actions }) => {
  const { createPage } = actions
  createPage({
    path: "/halaman-kustom",
    component: require.resolve("./src/templates/halaman.js"),
    context: {},
  })
}

createPage membuat halaman baru dengan path, component, dan context yang bisa diteruskan ke query. Detail lengkap pembuatan halaman programatis akan dibahas di episode 14.

#Environment Variables dan Build-Time Config

#File .env dan Konvensi Prefix

Gatsby membaca otomatis file .env.development dan .env.production saat command terkait dijalankan. Aturan kunci: hanya variabel berawalan GATSBY_ yang bisa dipakai di kode client (komponen React). Contoh:

GATSBY_API_URL=https://api.example.com
SITE_TITLE=Gatsby Belajar

Di gatsby-config.js, semua variabel bisa dipakai — termasuk yang tanpa prefix:

Gunakan env di gatsby-config

module.exports = {
  siteMetadata: {
    title: process.env.SITE_TITLE || "Gatsby Belajar",
  },
  plugins: [
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "content",
        path: `${__dirname}/content`,
      },
    },
  ],
}

process.env.SITE_TITLE tersedia di konfigurasi karena file ini berjalan di Node. Namun di komponen React, process.env.GATSBY_API_URL adalah satu-satunya cara mengakses env — hanya variabel GATSBY_ yang di-inject saat build.

#Source Plugins, Transformer Plugins, dan Schema Customization

#Source dan Transformer Bekerja Sama

Source plugins membuat node mentah (file, konten CMS), transformer mengubahnya menjadi tipe yang bisa di-query (MarkdownRemark, ImageSharp). Keduanya selalu berpasangan untuk data lokal.

#Kustomisasi Schema dengan createSchemaCustomization

Kadang kita perlu mengontrol tipe data Gatsby. Gunakan createSchemaCustomization dengan GraphQL SDL:

Kustomisasi schema

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type MarkdownRemark implements Node {
      frontmatter: Frontmatter
    }
    type Frontmatter {
      title: String!
      published: Boolean
      tags: [String!]
    }
  `
  createTypes(typeDefs)
}

createTypes dengan definisi tipe SDL memberi kepastian schema, misalnya published bertipe Boolean dan tags wajib array string.

#Mengelola Secret dan Pengaturan Per-Environment

#Secret Tidak Boleh Masuk Kode Client

Data sensitif seperti API key server dan token CMS hanya boleh dipakai di gatsby-config.js dan gatsby-node.js. Jangan pernah menaruh secret dengan prefix GATSBY_ karena akan ikut ter-bundle ke JavaScript yang dikirim ke browser.

#Praktik Aman

• Simpan secret di environment platform (Netlify, Vercel, Gatsby Cloud, atau CI/CD), bukan di repo.
• Tambahkan file .env* ke .gitignore.
• Untuk sourcing data yang butuh token — misalnya CMS — panggil process.env di options plugin yang dijalankan saat build.

#Memisahkan Pengaturan per Environment

Pola yang umum: file env terpisah untuk development dan production. Gatsby otomatis memilih berdasarkan command: gatsby develop memuat .env.development, gatsby build memuat .env.production. Jika butuh nilai berbeda untuk staging, beri nama sesuai platform dan override di pengaturan deployment.

Dengan pemisahan ini, perilaku dev dan production bisa berbeda — misalnya API URL yang berbeda dan mode debug yang diaktifkan hanya saat development.

#Penutup

Episode 8 menuntaskan konfigurasi: peran gatsby-config.js dan gatsby-node.js, konvensi environment variables dengan prefix GATSBY_, kustomisasi schema, serta pengelolaan secret yang aman.

Inti yang harus dibawa pulang:

• gatsby-config untuk deklarasi; gatsby-node untuk logika build.
• Hanya env berprefix GATSBY_ yang tersedia di kode client.
• createTypes dipakai untuk mengontrol schema data.
• Secret hanya di sisi build, tidak pernah dengan prefix GATSBY_.
• .env.development dan .env.production dimuat otomatis per command.
• .gitignore harus mencakup semua file .env*.

Di episode 9 selanjutnya kita akan membahas content management dan CMS integration — sourcing Markdown dan MDX, integrasi headless CMS seperti Contentful dan Strapi, preview mode, serta content modeling dan optimasi query.