Panduan Arsitektur Nuxt WordPress untuk Web Headless

Arsitektur Nuxt WordPress menggabungkan kemudahan pengelolaan konten WordPress di sisi backend dengan kecepatan rendering Nuxt (Vue 3) di sisi frontend. Dalam skema headless ini, WordPress bertindak murni sebagai penyedia data melalui WPGraphQL atau REST API, sedangkan Nuxt menangani antarmuka pengguna via Server-Side Rendering (SSR), Static Site Generation (SSG), atau Edge caching untuk menghasilkan situs yang cepat dan aman.

Banyak tim editorial menyukai antarmuka WordPress karena sudah terbiasa dengan alur penulisan, pustaka media, dan pengaturan taksonomi di dalamnya. Di sisi lain, developer kerap kesulitan saat harus mengurus tema PHP monolitik yang lambat, rentan celah keamanan plugin, dan sulit mencapai skor Core Web Vitals hijau. Memisahkan kedua lapisan ini memberikan jalan tengah terbaik bagi penulis konten dan tim rekayasa perangkat lunak.

Mengapa Memilih Arsitektur Nuxt WordPress Headless?

Pada instalasi WordPress tradisional, setiap kunjungan pengguna memicu eksekusi skrip PHP, memanggil kueri database MySQL di server yang sama, lalu merakit dokumen HTML secara utuh. Proses berulang ini kerap membebani Time to First Byte (TTFB), terlebih saat situs menjalankan puluhan plugin aktif.

Pendekatan Nuxt WordPress headless memutus rantai beban tersebut. Pengguna tidak lagi mengakses server WordPress secara langsung, melainkan berinteraksi dengan aplikasi Nuxt yang berjalan di atas Nitro Engine. Jika Anda baru mendalami ekosistem ini, pelajari konsep dasar mengenal Nuxt JS sebagai framework Vue SSR dan SSG untuk memahami cara kerja mesin renderingnya.

Saat beralih dari sistem tradisional ke kombinasi WordPress dan Nuxt, Anda tidak lagi membuat tema WordPress berbasis file index.php, single.php, atau functions.php. Seluruh tata letak antarmuka beralih menjadi aplikasi mandiri berbasis komponen Vue yang mengambil data melalui jalur API.

Berikut adalah perbandingan teknis antara arsitektur WordPress monolitik dan Nuxt dalam skenario produksi:

Karena server WordPress tidak lagi melayani trafik pengunjung secara langsung, Anda dapat menurunkan spesifikasi server backend. Sumber daya server cukup difokuskan pada kestabilan database serta object caching seperti Redis atau Memcached.

Memilih Jalur Data: WPGraphQL vs WP REST API

Langkah krusial pertama saat merancang integrasi Nuxt WordPress adalah menentukan protokol komunikasi data antara keduanya. WordPress menyediakan dua opsi utama dengan karakteristik berbeda:

1. WP REST API (Bawaan Core) Fitur ini langsung aktif tanpa plugin tambahan. Sayangnya, REST API bawaan sering mengalami over-fetching (mengambil terlalu banyak data JSON yang tidak terpakai di antarmuka) dan waterfall requests. Untuk merender satu halaman artikel lengkap dengan nama penulis, kategori, dan URL gambar sampul ukuran spesifik, aplikasi kadang harus mengirim beberapa panggilan HTTP beruntun atau memuat parameter _embed yang berukuran besar.
2. WPGraphQL (Standar De Facto Headless) Plugin WPGraphQL (versi 2.x) mengatasi masalah pembengkakan payload data pada arsitektur headless skala menengah hingga besar. Fitur DataLoader batching di dalamnya mampu memangkas jumlah kueri database hingga 60–80% dan mengizinkan pengambilan data tersarang (nested query) hanya dalam satu kali round-trip HTTP.

Untuk proyek jangka panjang, WPGraphQL jauh lebih unggul karena menjaga ukuran transfer jaringan tetap kecil dan sangat serasi dengan sistem type-safety di TypeScript.

Panduan Praktis Integrasi Nuxt 3/4 dengan WordPress

Bagian ini mempraktikkan cara membangun alur pengambilan data yang bersih, aman, dan siap pakai untuk lingkungan produksi menggunakan Nuxt dan WPGraphQL.

Persiapan Backend WordPress

Masuk ke dashboard admin WordPress Anda, lalu pasang dan aktifkan plugin WPGraphQL. Jika Anda menggunakan custom fields, pasang juga WPGraphQL for ACF. Agar aplikasi Nuxt dapat mengambil data tanpa terhalang kebijakan peramban, pasang plugin WPGraphQL CORS dan daftarkan domain lokal (http://localhost:3000) serta domain produksi Nuxt Anda.

Konfigurasi Endpoint dan Caching di Nuxt

Buka proyek Nuxt Anda dan atur variabel lingkungan di dalam nuxt.config.ts. Tambahkan juga konfigurasi routeRules dengan strategi Stale-While-Revalidate (SWR) agar halaman artikel tersimpan di cache selama satu jam (3600 detik).

typescript

Salin

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      wpGraphQLEndpoint: process.env.NUXT_PUBLIC_WP_GRAPHQL_ENDPOINT || 'https://backend.example.com/graphql'
    }
  },
  routeRules: {
    '/': { swr: 3600 },
    '/blog/**': { swr: 3600 }
  }
})

Pengambilan Data Artikel di Halaman Dinamis

Buat file halaman dinamis di pages/blog/[slug].vue. Gunakan composable useAsyncData yang dipadukan dengan $fetch bawaan Nitro untuk mengirim kueri GraphQL berdasarkan slug URL.

vue

Salin

<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
interface PostResponse {
  data: {
    post: {
      title: string
      content: string
      date: string
      featuredImage?: {
        node: {
          sourceUrl: string
          altText: string
        }
      }
    }
  }
}

const route = useRoute()
const config = useRuntimeConfig()
const slug = route.params.slug as string

const QUERY_POST = `
  query GetPostBySlug($id: ID!) {
    post(id: $id, idType: SLUG) {
      title
      content
      date
      featuredImage {
        node {
          sourceUrl(size: LARGE)
          altText
        }
      }
    }
  }
`

const { data, pending, error } = await useAsyncData(`post-${slug}`, async () => {
  const res = await $fetch<PostResponse>(config.public.wpGraphQLEndpoint, {
    method: 'POST',
    body: {
      query: QUERY_POST,
      variables: { id: slug }
    }
  })
  return res.data.post
})

useSeoMeta({
  title: () => data.value?.title ?? 'Artikel Blog',
  ogImage: () => data.value?.featuredImage?.node?.sourceUrl
})
</script>

<template>
  <main class="max-w-4xl mx-auto px-4 py-8">
    <div v-if="pending">Memuat artikel...</div>
    <div v-else-if="error || !data">Artikel tidak ditemukan.</div>
    <article v-else class="prose lg:prose-xl">
      <h1 class="text-3xl font-bold mb-4">{{ data.title }}</h1>
      <img
        v-if="data.featuredImage?.node?.sourceUrl"
        :src="data.featuredImage.node.sourceUrl"
        :alt="data.featuredImage.node.altText || data.title"
        class="rounded-lg mb-6"
        loading="lazy"
      />
      <div v-html="data.content" />
    </article>
  </main>
</template>

Untuk mempercepat pembuatan antarmuka halaman blog di atas, Anda dapat memadukannya dengan pustaka komponen siap pakai. Ikuti panduan membangun antarmuka cepat dengan Nuxt UI untuk merancang tata letak tipografi dan navigasi yang konsisten.

Strategi Tingkat Lanjut untuk Skala Produksi

Banyak tutorial dasar berhenti setelah data berhasil tampil di layar. Padahal, tantangan sesungguhnya dari arsitektur Nuxt WordPress muncul ketika situs dikelola oleh banyak editor dan menerima trafik tinggi. Tiga pendekatan arsitektur berikut akan membedakan proyek eksperimental dari sistem kelas produksi.

1. Edge Caching dan On-Demand Revalidation via Nitro Webhook

Aturan swr: 3600 memang meringankan beban server, tetapi editor sering kali ingin melihat perubahan artikel tayang seketika saat menekan tombol Publish atau Update di WordPress. Melakukan re-build seluruh situs statis setiap kali ada koreksi salah ketik tentu membuang waktu.

Solusinya adalah membuat endpoint webhook di Nitro Server (misalnya server/api/revalidate.post.ts). Saat editor memperbarui konten di WordPress, action hook save_post di PHP menembakkan permintaan HTTP POST berisi slug artikel dan token rahasia ke endpoint Nitro tersebut. Server Nuxt kemudian menghapus cache spesifik hanya untuk halaman terkait di lapisan penyimpanan Nitro atau CDN Edge. Pola ini selaras dengan prinsip arsitektur backend dan integrasi modern Nuxt yang memanfaatkan komputasi tepi secara efisien.

typescript

Salin

// server/api/revalidate.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody<{ secret?: string; slug?: string }>(event)
  const config = useRuntimeConfig()

  if (body.secret !== config.revalidateSecret || !body.slug) {
    throw createError({ statusCode: 401, statusMessage: 'Akses ditolak' })
  }

  // Menghapus cache spesifik di Nitro storage
  const storage = useStorage('cache')
  await storage.removeItem(`nitro:routes:blog:${body.slug}.json`)

  return { revalidated: true, slug: body.slug }
})

2. Parsing Blok Gutenberg Menjadi Komponen Vue Individual

Merender seluruh isi artikel dengan direktif v-html="data.content" adalah cara tercepat, tetapi Anda akan kehilangan interaktivitas Vue di tengah artikel. Jika Anda ingin menyisipkan komponen galeri interaktif, tabel harga dinamis, atau kotak peringatan bergaya khusus, string HTML mentah akan terasa kaku.

Pendekatan yang lebih rapi adalah memasang ekstensi WPGraphQL Content Blocks. Alih-alih meminta satu string HTML utuh, aplikasi meminta array objek JSON yang merepresentasikan setiap blok Gutenberg (core/paragraph, core/heading, core/image, hingga blok kustom ACF). Di sisi Nuxt, Anda membuat komponen pembungkus yang melakukan perulangan (v-for) dan merender komponen Vue yang sesuai memakai <component :is="resolveBlock(block.name)" />. Anda memegang kendali desain penuh dengan kelas Tailwind CSS di tiap komponen.

3. Isolasi Penuh Server Backend untuk Keamanan

Keuntungan terbesar memisahkan WordPress dari antarmuka publik adalah kemampuan menyembunyikan instalasi CMS tersebut. Karena pengguna akhir hanya mengakses domain aplikasi Nuxt, subdomain tempat WordPress berada (misalnya cms-internal.domain.com) tidak perlu dibuka untuk umum.

Anda dapat meletakkan server WordPress di balik jaringan privat (VPN) dan mengatur IP Whitelisting pada firewall agar halaman wp-login.php hanya bisa diakses oleh alamat IP tim editor. Akses publik ke endpoint /graphql juga dapat dibatasi khusus untuk alamat IP server Nuxt. Serangan brute-force login dan eksploitasi celah keamanan plugin frontend pun tertutup rapat.

Lima Kesalahan Umum Implementasi Headless dan Solusinya

Berpindah dari arsitektur monolitik ke decoupled menuntut perubahan pola pikir. Berikut adalah lima jebakan teknis yang paling sering dialami developer saat membangun proyek Nuxt WordPress beserta cara mengatasinya.

1. Mengambil Gambar Ukuran Penuh (Over-fetching Media) Banyak developer langsung memanggil sourceUrl pada kueri featuredImage tanpa argumen tambahan. Akibatnya, WordPress mengirimkan URL gambar asli beresolusi penuh yang membebani jaringan. Selalu tentukan parameter ukuran di dalam kueri GraphQL Anda, seperti sourceUrl(size: MEDIUM_LARGE) atau LARGE, lalu padukan dengan modul @nuxt/image untuk kompresi modern secara otomatis.
2. Terjebak Masalah CORS Saat Development dan Produksi Ketika kode pengambilan data dieksekusi di peramban saat perpindahan halaman (client-side navigation), peramban sering memblokir permintaan ke domain WordPress karena kebijakan Cross-Origin Resource Sharing (CORS). Selain mengatur header CORS di server WordPress, solusi paling rapi di Nuxt adalah membuat server proxy melalui folder server/api/. Dengan cara ini, peramban meminta data ke server Nuxt sendiri, lalu Nitro menghubungi server WordPress secara server-to-server tanpa hambatan CORS.
3. Kehilangan Fitur Preview Draft bagi Editor Saat editor menekan tombol Preview pada draf artikel di dashboard WordPress, mereka akan diarahkan ke URL PHP bawaan yang kosong atau rusak. Untuk memperbaikinya, buat route khusus di Nuxt (misalnya /preview) yang menangkap parameter ID revisi dan token autentikasi JWT dari WordPress, lalu jalankan kueri GraphQL berautentikasi untuk menampilkan draf yang belum terbit.
4. Mengira Semua Plugin WordPress Otomatis Bekerja Plugin yang memanipulasi tampilan frontend melalui injeksi skrip PHP, seperti Contact Form 7, form builder monolitik, atau shortcode galeri lawas, tidak akan berfungsi di Nuxt. Anda hanya bisa memanfaatkan plugin yang mengekspos datanya ke API. Untuk formulir kontak, bangun komponen formulir langsung di Vue dan kirim datanya ke endpoint REST/GraphQL atau layanan webhook terpisah.
5. Melupakan Pemetaan URL SEO dan Redirect Saat memigrasikan situs WordPress lama ke Nuxt, jaga struktur permalink agar tetap sama supaya peringkat mesin pencari tidak turun. Tarik juga data meta title, description, dan canonical URL dari plugin SEO di WordPress melalui ekstensi GraphQL, lalu pasang ke dalam composable useSeoMeta() di Nuxt.