Pengenalan

nuxt-gsheet adalah modul integrasi Google Sheets zero-config, berkinerja tinggi, dan aman untuk Nuxt 3 dan Nuxt 4. Modul ini memungkinkan kamu menggunakan Google Sheets sebagai CMS ringan atau database secara seamless dengan keamanan server-side proxy, stampede-proof caching, multi-mode autentikasi, dan tab khusus di Nuxt DevTools.

Mengapa nuxt-gsheet?

Google Sheets sangat populer digunakan sebagai content management system (CMS), database prototipe, maupun penyimpanan data cepat karena kemudahannya dan fitur kolaborasi real-time. Namun, melakukan query ke Google Sheets secara langsung dari aplikasi frontend menyimpan beberapa kendala utama:

• Risiko Keamanan: Mengekspos Spreadsheet ID, API Key, atau kredensial Service Account secara langsung di client-side dapat memicu penyalahgunaan akses dan pencurian API key.
• Batas Kuota & Rate Limit: Request yang terlalu sering dari client-side akan dengan cepat menghabiskan kuota Google API atau memicu pembatasan eksekusi Google Apps Script.
• Cache Stampede: Saat banyak pengguna mengakses situs secara bersamaan ketika cache kedaluwarsa, ratusan request serentak akan membanjiri endpoint Google API, menyebabkan error rate limit (HTTP 429).
• Kompleksitas Setup: Mengatur alur antara public sheet, proxy Google Apps Script, endpoint GViz, dan private Service Account biasanya mengharuskan kita menulis backend proxy sendiri.

nuxt-gsheet menyelesaikan seluruh masalah tersebut secara out-of-the-box tanpa perlu konfigurasi rumit.

Fitur Utama

• ⚡️ Auto-Detection Multi-Auth: Mendukung Google Sheets API v4 (API Key & Service Account), proxy Google Apps Script Web App, Google Visualization API (GViz), dan ekspor CSV langsung.
• 🔒 Secure Server Proxy: Meng-intercept request di sisi server (/api/_gsheet/*). Kredensial dan endpoint spreadsheet tetap tersembunyi dengan aman dari client browser.
• 🛡️ Perlindungan Cache Stampede: Tetap menyajikan stale cache saat terjadi kegagalan jaringan atau pembatasan kuota, serta menggabungkan request identik yang terjadi bersamaan menjadi satu request upstream saja.
• 🧪 Type-Safe Composables: Menyediakan Vue composable ter-auto-import (useGSheet, useGSheetAsObject, useGSheetRow, dan useGSheetWrite) dengan auto-completion TypeScript penuh.
• 📊 Integrasi Nuxt DevTools: Memantau request API yang ter-intercept, rasio cache hit/miss, mode auth yang aktif, dan estimasi penggunaan kuota langsung dari Nuxt DevTools.

Cara Kerja

nuxt-gsheet bertindak sebagai middleware penyeimbang antara aplikasi Nuxt kamu dan Google Sheets.

1. Client Request: Komponen Vue memanggil composable seperti useGSheetAsObject('A1:C10').
2. Server Handling: Request diarahkan ke Nitro server internal milik Nuxt (/api/_gsheet/*).
3. Cache & Stampede Check: Jika data valid tersedia di cache, data langsung dikembalikan. Jika cache sudah usang atau belum ada, hanya satu request yang dikirim ke Google Sheets, seberapa banyak pun komponen client yang memintanya secara bersamaan.
4. Data Formatting: Nilai cell mentah dikonversi menjadi objek JavaScript atau array berstruktur dan dikembalikan secara aman ke aplikasi client.

Prasyarat

Sebelum memulai, pastikan lingkungan pengembangan kamu memenuhi prasyarat berikut:

• Nuxt: Versi ^3.10.0 atau Nuxt 4.x
• Node.js: Versi ^18.0.0 atau lebih baru (atau Bun ^1.0.0)

Langkah Selanjutnya

Setelah memahami konsep dasar nuxt-gsheet, kamu siap memasangnya di proyekmu:

• Instalasi & Panduan Cepat
• Referensi Konfigurasi
• Gambaran Umum Composables