Belajar Nuxt - Configuration & Runtime Config

#Pendahuluan

Semakin besar project, semakin penting konfigurasi yang terpusat dan aman. Episode 8 membahas cara mengatur Nuxt dengan benar: apa yang hidup di nuxt.config.ts saat build, dan apa yang baru diketahui saat runtime lewat runtime config.

Kesalahan yang paling sering terjadi: menyimpan API key di file frontend, atau mengubah-ubah nuxt.config.ts untuk nilai yang sebenarnya bergantung environment. Setelah episode ini, kalian akan paham kapan memakai apa, dan bagaimana feature flags serta build optimizations bisa dikelola secara terstruktur.

#nuxt.config.ts sebagai Pusat Konfigurasi

#Satu Sumber Kebenaran Saat Build

Semua opsi build dan modul tinggal di nuxt.config.ts. Contoh konfigurasi umum untuk project belajar-shop:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@pinia/nuxt", "@nuxt/image"],
  css: ["~/assets/css/main.css"],
  app: {
    head: {
      title: "Belajar Shop",
      meta: [{ name: "description", content: "Toko contoh belajar Nuxt" }],
    },
  },
})

Opsi app.head mengatur title dan meta tags global yang dirender di setiap halaman. Perubahan di file ini membutuhkan restart dev server, karena dia hanya dibaca saat build dimulai.

#Komponen RuntimeConfig

runtimeConfig adalah bagian dari nuxt.config.ts yang nilainya bisa diganti saat runtime tanpa rebuild. Nilai di dalamnya dibaca dari environment variables:

Runtime config dengan env

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: process.env.API_KEY,
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || "/api",
    },
  },
})

runtimeConfig dibagi dua: nilai default di public bisa diakses client, dan nilai di luar public hanya tersedia di server. Environment variable otomatis di-override dengan aturan penamaan.

#Environment Variables dan Public/Private Config

#Aturan Penamaan Environment

Nuxt membaca environment variables berdasarkan nama. Untuk nilai public, nama variabelnya NUXT_PUBLIC_*; untuk nilai private, NUXT_*:

NUXT_PUBLIC_API_BASE=https://api.belajarshop.dev
NUXT_API_KEY=rahasia-jangan-bocor
NUXT_PUBLIC_SITE_URL=https://belajarshop.dev

File .env di atas tidak boleh di-commit ke git — tambahkan ke .gitignore. Perhatikan satu hal penting: variabel tanpa awalan NUXT_ tidak otomatis terbaca oleh Nuxt.

#Public vs Private

Perbedaan krusial:

• Public config dikirim ke browser. Hanya taruh nilai yang aman dilihat publik seperti base URL.
• Private config hanya ada di server, dibaca lewat config.apiKey. Jangan pernah memakai nilainya di komponen client-side.

Membaca config di server

const config = useRuntimeConfig()
 
async function getDataEksternal() {
  return await $fetch("https://api.eksternal.dev/v1", {
    headers: { Authorization: `Bearer ${config.apiKey}` },
  })
}

config.apiKey di atas hanya boleh dipanggil di kode server — misalnya di server/api. Jika dipanggil di komponen, nilainya menjadi undefined karena tidak dikirim ke client.

#Konfigurasi Modules dan Plugins

#Mengirim Opsi ke Module

Banyak module menerima opsi lewat array dalam modules:

Module dengan opsi

export default defineNuxtConfig({
  modules: [
    "@nuxt/image",
    ["@nuxtjs/i18n", { locales: ["id", "en"], defaultLocale: "id" }],
  ],
})

Untuk module dengan banyak opsi, bentuk array ["nama-module", opsi] lebih mudah dibaca. Setiap module mendokumentasikan opsi yang didukungnya.

#Plugins Aplikasi

Plugins Nuxt adalah kode yang dijalankan saat aplikasi diinisialisasi, didefinisikan di app/plugins. Konfigurasi mereka biasanya menyangkut library pihak ketiga yang butuh setup di awal.

#Build Optimizations dan Feature Flags

#Optimasi Build

Nuxt mengoptimasi build secara otomatis — pembagian code chunks, minifikasi, dan tree-shaking. Kalian bisa ikut mengatur lewat opsi build.transpile untuk library tertentu, atau mengaktifkan eksperimen:

Opsi build

export default defineNuxtConfig({
  build: {
    transpile: ["beberapa-library"],
  },
  features: {
    inlineStyles: true,
  },
})

#Feature Flags

Feature flags memungkinkan fitur diaktifkan atau dinonaktifkan tanpa menulis ulang kode. Kombinasikan runtime config dengan kondisi di komponen:

Feature flag lewat runtime config

const config = useRuntimeConfig()
const promoAktif = computed(() => config.public.promoAktif === "true")

Nilai config.public.promoAktif berasal dari NUXT_PUBLIC_PROMO_AKTIF di .env. Ubah nilai env, restart, dan fitur promo langsung berubah tanpa mengubah kode.

#Penutup

Episode 8 menjadikan konfigurasi kalian terpusat dan aman: nuxt.config.ts untuk semua yang diketahui saat build, runtime config untuk nilai yang berubah saat runtime, pemisahan tegas antara config public dan private, serta feature flags yang dikendalikan lewat environment variables.

Inti yang harus dibawa pulang:

• nuxt.config.ts adalah satu-satunya sumber kebenaran konfigurasi build.
• runtimeConfig menggabungkan nilai statis dengan environment variables.
• Public config harus aman untuk browser; private config hanya untuk server.
• Variabel public memakai awalan NUXT_PUBLIC_, private memakai NUXT_.
• Jangan pernah memakai private config di kode client-side.
• Feature flags bisa dikendalikan lewat runtime config tanpa mengubah kode.

Di episode 9 selanjutnya kita akan membahas images dan assets — optimasi gambar dengan @nuxt/image, pengelolaan static assets dan folder public, responsive images dengan lazy loading, serta strategi media optimization untuk performa. Toko kalian akan tampil tajam dan cepat.