Airtable’ı Gatsby ile Kullanmak: Kapsamlı Bir Teknik Rehber

Airtable’ı Gatsby ile Kullanmak: Kapsamlı Bir Teknik Rehber

Modern web geliştirme dünyasında, hızlı yüklenen, güvenli ve ölçeklenebilir web siteleri oluşturmak büyük önem taşımaktadır. Bu hedeflere ulaşmak için Gatsby gibi statik site oluşturucular (SSG) ve Airtable gibi esnek, API odaklı içerik yönetim sistemleri (CMS) veya veri tabanı çözümleri mükemmel bir ikili oluşturur. Bu rehberde, Airtable’ı bir içerik kaynağı olarak kullanarak Gatsby ile nasıl dinamik web siteleri oluşturacağınızı adım adım inceleyeceğiz.

Neden Airtable ve Gatsby?

Airtable, geleneksel bir elektronik tablo arayüzünün basitliğini, güçlü bir ilişkisel veri tabanının esnekliğiyle birleştiren hibrit bir araçtır. Verilerinizi düzenleyebilir, farklı alan tipleriyle (metin, sayı, resim, tarih, çoktan seçmeli vb.) zenginleştirebilir ve güçlü bir API aracılığıyla bu verilere kolayca erişebilirsiniz. Bu özellikler, Airtable’ı bir headless CMS, ürün kataloğu, proje yönetim aracı veya basit bir blog için ideal bir veri depolama çözümü haline getirir.

Gatsby ise React tabanlı, yüksek performanslı bir statik site oluşturucudur. Geliştirme sürecinde GraphQL kullanarak farklı veri kaynaklarından (API’ler, Markdown dosyaları, CMS’ler) veri çekebilir ve bu verileri önceden derlenmiş, optimize edilmiş statik HTML, CSS ve JavaScript dosyalarına dönüştürür. Sonuç olarak, siteleriniz inanılmaz derecede hızlı yüklenir, güvenlidir ve düşük barındırma maliyetlerine sahiptir.

Bu iki teknolojinin birleşimi, içerik yöneticilerinin Airtable’ın kullanıcı dostu arayüzünde içeriklerini kolayca yönetirken, geliştiricilerin Gatsby’nin gücüyle hızlı, SEO dostu ve modern web deneyimleri sunmasına olanak tanır.

Ortam Kurulumu ve Airtable Hazırlığı

Airtable verilerinizi Gatsby uygulamanızda kullanmaya başlamadan önce, hem yerel geliştirme ortamınızı hem de Airtable base’inizi hazırlamanız gerekir.

Gatsby CLI Kurulumu ve Yeni Proje Oluşturma

İlk olarak, Gatsby komut satırı arayüzünü (CLI) küresel olarak yüklemeniz gerekir:

npm install -g gatsby-cli

Ardından, yeni bir Gatsby projesi oluşturun ve proje dizinine gidin:

gatsby new my-airtable-gatsby-app
cd my-airtable-gatsby-app

Bu komutlar, temel bir Gatsby projesi yapısını oluşturacaktır.

Airtable Hesabı ve Base Oluşturma

1. Airtable Hesabı Oluşturma: Eğer bir Airtable hesabınız yoksa, Airtable web sitesinden ücretsiz bir hesap oluşturun.
2. Yeni Bir Base Oluşturma: Hesabınıza giriş yaptıktan sonra, “Add a base” veya “Yeni bir base ekle” seçeneğiyle yeni bir base oluşturun. Örneğin, “Gatsby Ürün Kataloğu” adında bir base oluşturabilirsiniz.
3. Tablo ve Alanlar Oluşturma: Base’inizin içinde, verilerinizi tutacak bir tablo oluşturun. Varsayılan olarak “Table 1” adında bir tablo bulunur, adını “Ürünler” olarak değiştirebilirsiniz. Ardından, ürünleriniz için gerekli alanları (fields) tanımlayın. Örneğin:
* Başlık (Single line text)
* Açıklama (Long text)
* Fiyat (Number, Currency format)
* Stok Durumu (Single select, seçenekler: “Stokta”, “Tükendi”)
* Resim (Attachment)
* Yayın Tarihi (Date)

Bu alanları oluşturduktan sonra, birkaç örnek ürün verisi ekleyin. Özellikle Resim alanı için dosya yüklemeyi unutmayın.

Airtable API Anahtarı ve Base ID Alma

Gatsby uygulamanızın Airtable verilerine erişebilmesi için API anahtarınıza ve base ID’nize ihtiyacınız olacak.

1. API Anahtarı: Airtable hesabınıza giriş yapın, sağ üst köşedeki profil fotoğrafınıza tıklayın ve “Account” (Hesap) seçeneğine gidin. Sol menüde “API” sekmesini bulacaksınız. Burada “YOUR API KEY” etiketli anahtarınızı göreceksiniz. Bu anahtarı kopyalayın.
ÖNEMLİ GÜVENLİK NOTU: Bu anahtar özeldir ve asla genel bir depoda (GitHub gibi) açıkça yayımlanmamalıdır. Ortam değişkenleri kullanarak güvenliğini sağlayacağız.
2. Base ID: Base ID’nizi bulmanın en kolay yolu, Airtable API belgelerine gitmektir. https://airtable.com/api adresine gidin. Burada tüm base’lerinizin listesini göreceksiniz. İlgili base’inize tıkladığınızda, dokümantasyon sayfasının URL’sinde appXXXXXXXXX formatında bir Base ID göreceksiniz. Örneğin: https://airtable.com/appXXXXXXXXX/api/docs. Bu ID’yi kopyalayın.

Gatsby ile Airtable Entegrasyonu

Artık Airtable verilerimiz hazır ve API anahtarlarımız mevcut. Şimdi Gatsby uygulamamızı Airtable’dan veri çekmek üzere yapılandıralım.

Gatsby Kaynak Eklentisi Kurulumu

Gatsby, farklı veri kaynaklarından veri çekmek için “kaynak eklentileri” (source plugins) kullanır. Airtable için gatsby-source-airtable eklentisini kullanacağız.

Proje dizininizde bu eklentiyi ve ortam değişkenlerini yönetmek için dotenv paketini yükleyin:

npm install gatsby-source-airtable dotenv

Ortam Değişkenlerini Yapılandırma (.env)

API anahtarınızı ve base ID’nizi doğrudan kodunuza yazmak yerine, ortam değişkenleri kullanmak en iyi pratiktir. Projenizin kök dizininde .env adında bir dosya oluşturun ve içine aşağıdaki satırları ekleyin (kendi anahtar ve ID’nizle değiştirerek):

AIRTABLE_API_KEY=YOUR_AIRTABLE_API_KEY
AIRTABLE_BASE_ID=YOUR_AIRTABLE_BASE_ID

Ardından, bu .env dosyasının git deposuna yüklenmesini engellemek için .gitignore dosyanıza aşağıdaki satırı ekleyin:

.env

gatsby-config.js Yapılandırması

Gatsby uygulamanızın ana yapılandırma dosyası olan gatsby-config.js dosyasını açın. dotenv paketini dosyanın en üstünde çağırarak ortam değişkenlerinizi yükleyin ve gatsby-source-airtable eklentisini plugins dizisine ekleyin:

require('dotenv').config({
  path: .env.${process.env.NODE_ENV}, // Ortam değişkenlerini yüklemek için path belirtme
});

module.exports = {
  siteMetadata: {
    title: Gatsby Airtable Örneği,
    description: Airtable'dan veri çeken bir Gatsby uygulaması.,
    author: @gatsbyjs,
  },
  plugins: [
    gatsby-plugin-react-helmet,
    {
      resolve: gatsby-source-filesystem,
      options: {
        name: images,
        path: ${__dirname}/src/images,
      },
    },
    gatsby-transformer-sharp,
    gatsby-plugin-sharp,
    {
      resolve: gatsby-plugin-manifest,
      options: {
        name: gatsby-starter-default,
        short_name: starter,
        start_url: /,
        background_color: #663399,
        theme_color: #663399,
        display: minimal-ui,
        icon: src/images/gatsby-icon.png, // Bu yolu kendi ikonunuzla değiştirin
      },
    },
    // Airtable kaynak eklentisi
    {
      resolve: 'gatsby-source-airtable',
      options: {
        apiKey: process.env.AIRTABLE_API_KEY, // .env dosyasından API anahtarı
        baseId: process.env.AIRTABLE_BASE_ID, // .env dosyasından Base ID
        tables: [
          {
            baseId: process.env.AIRTABLE_BASE_ID,
            tableName: 'Ürünler', // Airtable'daki tablo adınız
            // tableView: 'Grid view', // İsteğe bağlı: Belirli bir görünümden veri çekmek isterseniz
            // queryName: 'products', // İsteğe bağlı: GraphQL sorgularında kullanmak için bir isim
            // mapping: { Resim: fileNode }, // İsteğe bağlı: Resim alanlarını Gatsby'nin dosya düğümlerine dönüştürmek için
          },
          // Eğer birden fazla tabloya sahipseniz, buraya ekleyebilirsiniz:
          // {
          //   baseId: process.env.AIRTABLE_BASE_ID,
          //   tableName: 'Blog Yazıları',
          //   // ... diğer seçenekler
          // },
        ],
      },
    },
    // Bu eklentiyi en sona ekleyin
    gatsby-plugin-offline,
  ],
};

Yukarıdaki yapılandırmada, tables dizisi içine Airtable base’inizdeki her bir tablo için bir nesne eklemeniz gerekir. tableName özelliğini kendi tablo adınızla değiştirmeyi unutmayın (“Ürünler” örneğimizde).

Yapılandırma dosyasını kaydettikten sonra, geliştirme sunucunuzu yeniden başlatmanız gerekir:

gatsby develop

Veri Çekme ve GraphQL

Gatsby geliştirme sunucusu çalışırken, tarayıcınızda http://localhost:8000/___graphql adresine giderek GraphQL arayüzünü açın. Burada, Airtable’dan çekilen verileri keşfedebilirsiniz.

Sol taraftaki “Explorer” bölümünde, allAirtable veya airtable gibi seçenekler göreceksiniz. allAirtable‘a tıklayın, ardından nodes ve data altındaki alanlarınızı seçin. Örneğin:

query MyAirtableProducts {
  allAirtable(filter: {table: {eq: "Ürünler"}}) {
    nodes {
      id
      data {
        Başlık
        Açıklama
        Fiyat
        Resim {
          url
          filename
        }
        Stok_Durumu
        Yayın_Tarihi
      }
    }
  }
}

Yukarıdaki sorguyu çalıştırdığınızda, Airtable’daki “Ürünler” tablonuzdan çekilen verileri JSON formatında göreceksiniz. Alan adlarının GraphQL’de genellikle küçük harfle başladığına veya boşlukların _ ile değiştirildiğine dikkat edin (örneğin “Stok Durumu” -> Stok_Durumu). Resim alanı, bir dizi nesne olarak gelir ve url özelliğini kullanarak resim linkine erişebilirsiniz.

Verileri Gatsby Uygulamasında Görüntüleme

Artık GraphQL ile Airtable verilerine erişebildiğimize göre, bu verileri Gatsby sayfalarınızda veya bileşenlerinizde görüntüleyebiliriz.

Sayfa Bileşeni Oluşturma ve Verileri Görüntüleme

src/pages/index.js dosyasını açın ve içeriğini aşağıdaki gibi güncelleyin veya src/pages/urunler.js adında yeni bir dosya oluşturun:

import React from 'react';
import { graphql } from 'gatsby';

const UrunlerSayfasi = ({ data }) => {
  const urunler = data.allAirtable.nodes;

  return (
    

      
      
Airtable'dan çekilen ürünler:
      

        {urunler.map(urun => (
          

            
{urun.data.Başlık}
            {urun.data.Resim && urun.data.Resim.length > 0 && (
              
            )}
            
{urun.data.Açıklama}
            
Fiyat: {urun.data.Fiyat} TL
            
Stok Durumu: {urun.data.Stok_Durumu}
            Yayın Tarihi: {new Date(urun.data.Yayın_Tarihi).toLocaleDateString('tr-TR')}
          
        ))}
      
    
  );
};

export const query = graphql
  query AirtableUrunlerQuery {
    allAirtable(filter: { table: { eq: "Ürünler" } }, sort: { fields: data___Yayın_Tarihi, order: DESC }) {
      nodes {
        id
        data {
          Başlık
          Açıklama
          Fiyat
          Resim {
            url
            filename
            thumbnails {
              large {
                url
              }
            }
          }
          Stok_Durumu
          Yayın_Tarihi
        }
      }
    }
  }
;

export default UrunlerSayfasi;

Bu kodda:

1. graphql etiketli bir sorgu tanımlıyoruz. Bu sorgu, allAirtable düğümünden “Ürünler” tablosundaki tüm verileri çeker. sort parametresiyle verileri yayın tarihine göre sıralıyoruz.
2. Sorgu sonuçları, sayfa bileşenimize data prop’u olarak otomatik olarak iletilir.
3. data.allAirtable.nodes dizisini kullanarak ürünler üzerinde döngü yapıyoruz.
4. Her ürünün verilerine urun.data.Başlık, urun.data.Açıklama gibi alan adlarıyla erişiyoruz.
5. Resim alanı bir dizi nesne döndürdüğü için, urun.data.Resim[0].url ile ilk resmin URL’sine erişiyoruz.
6. Stok_Durumu gibi alanları koşullu olarak renklendirmek gibi basit stil uygulamaları ekliyoruz.
7. Tarih alanlarını toLocaleDateString ile okunabilir bir formata dönüştürüyoruz.

Dosyayı kaydedin ve http://localhost:8000/ (veya http://localhost:8000/urunler eğer urunler.js olarak kaydettiyseniz) adresini ziyaret edin. Airtable’dan çektiğiniz ürünlerin Gatsby uygulamanızda görüntülendiğini göreceksiniz!

Dinamik Sayfalar Oluşturma (İsteğe Bağlı)

Eğer her ürün için ayrı bir sayfa oluşturmak isterseniz, bu durumda gatsby-node.js dosyasını kullanmanız gerekir. Bu dosya, Gatsby’nin build aşamasında Node.js ortamında çalışır ve createPages API’sini kullanarak programatik olarak sayfalar oluşturmanıza olanak tanır.

Örneğin, her ürün için /urunler/urun-adi şeklinde bir URL oluşturabilirsiniz:

// gatsby-node.js
const path = require('path');

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;
  const productTemplate = path.resolve('./src/templates/product-detail.js');

  const result = await graphql(
    query {
      allAirtable(filter: { table: { eq: "Ürünler" } }) {
        nodes {
          id
          data {
            Başlık
          }
        }
      }
    }
  );

  if (result.errors) {
    throw result.errors;
  }

  const products = result.data.allAirtable.nodes;

  products.forEach(product => {
    createPage({
      path: /urunler/${product.data.Başlık.toLowerCase().replace(/ /g, '-')}/,
      component: productTemplate,
      context: {
        id: product.id, // Sayfaya geçilecek veri
      },
    });
  });
};

Ardından, src/templates/product-detail.js adında bir şablon dosyası oluşturarak belirli bir ürünün detaylarını görüntüleyebilirsiniz. Bu şablon, context olarak iletilen id değerini kullanarak ilgili ürünün detaylarını GraphQL ile çeker.

Sonuç ve Sıkça Sorulan Sorular (SSS)

Airtable ve Gatsby’nin birleşimi, içerik yönetimi esnekliği ile yüksek performanslı, statik web siteleri oluşturma yeteneğini bir araya getirerek güçlü bir çözüm sunar. Bu rehberde öğrendiğiniz adımlarla, kendi Airtable destekli Gatsby projelerinizi oluşturmaya hazırsınız. İster basit bir blog, ister kapsamlı bir ürün kataloğu veya bir proje yönetim paneli olsun, bu ikili size hızlı ve ölçeklenebilir bir temel sağlayacaktır.

Sıkça Sorulan Sorular (SSS)

1. Airtable’dan sadece belirli verileri nasıl çekerim?

GraphQL sorgularınızda filter argümanını kullanabilirsiniz. Örneğin, sadece stokta olan ürünleri çekmek için:
allAirtable(filter: { table: { eq: "Ürünler" }, data: { Stok_Durumu: { eq: "Stokta" } } }) { ... }
GraphQL arayüzünde (/___graphql) Explorer’ı kullanarak filtreleme seçeneklerini keşfedebilirsiniz.

2. Airtable’daki bir alanın adı değişirse ne olur?

Airtable’daki bir alanın adını değiştirdiğinizde, Gatsby’nin GraphQL şeması bu değişikliği otomatik olarak algılamayabilir. Geliştirme sunucunuzu (gatsby develop) yeniden başlatmanız veya gatsby clean komutunu çalıştırıp ardından gatsby develop ile önbelleği temizleyip şemayı yeniden oluşturmanız gerekebilir. GraphQL arayüzünde yeni alan adını kontrol edin.

3. Airtable’daki resimleri nasıl optimize ederim?

gatsby-source-airtable eklentisi mapping seçeneği ile Airtable’daki Attachment (ek) alanlarını Gatsby’nin dosya düğümlerine dönüştürmenize olanak tanır. Daha sonra gatsby-plugin-image ve gatsby-plugin-sharp gibi eklentilerle resimleri otomatik olarak optimize edebilir, farklı boyutlarda oluşturabilir ve tembel yükleme (lazy loading) gibi özelliklerden faydalanabilirsiniz. Bu, daha gelişmiş bir konudur ve ayrı bir rehber gerektirebilir.

4. Gatsby üzerinden Airtable’a veri yazabilir miyim?

Gatsby, bir statik site oluşturucu olduğu için, build aşamasında Airtable’dan sadece veri okur. Çalışma zamanında (runtime) Airtable’a veri yazmak için, doğrudan Airtable API’sini kullanarak (örneğin bir React bileşeninden) veya bir sunucusuz fonksiyon (serverless function) aracılığıyla HTTP POST istekleri göndermeniz gerekir. Bu, Gatsby’nin birincil kapsamının dışındadır ve genellikle bir form gönderme veya kullanıcı etkileşimi gibi durumlar için kullanılır.

5. Uygulamamı dağıtırken nelere dikkat etmeliyim?

Uygulamanızı dağıtırken (örneğin Netlify, Vercel gibi platformlara), ortam değişkenlerinizin doğru şekilde ayarlandığından emin olmalısınız. Dağıtım platformlarının ortam değişkenlerini ayarlama bölümlerini kullanarak AIRTABLE_API_KEY ve AIRTABLE_BASE_ID değerlerini girmeniz gerekecektir. Bu, build aşamasında Gatsby’nin Airtable verilerine erişmesini sağlar.