Belajar Astro - Configuration & Environment

#Pendahuluan

Semakin besar project, semakin penting konfigurasi yang rapi. Episode 8 ini membahas pusat pengaturan Astro: file astro.config.mjs, environment variables, integrasi plugin dan adapter, serta cara mengoptimalkan build dan mengatur output path.

Konfigurasi sering dianggap membosankan, padahal di sinilah banyak masalah produksi lahir: variabel environment yang bocor, output yang salah, atau adapter yang tidak cocok dengan hosting. Dengan pemahaman yang benar, kalian bisa mencegah masalah sebelum terjadi.

Episode ini memberi kalian fondasi konfigurasi yang akan dipakai di seluruh fase produksi series ini.

#astro.config.mjs dan Pengaturan Dasar

#Konfigurasi Inti

astro.config.mjs adalah satu-satunya file konfigurasi yang wajib. Berikut contoh yang sudah cukup lengkap:

astro.config.mjs lengkap

import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
 
export default defineConfig({
  site: "https://blog.contoh.dev",
  base: "/blog",
  output: "static",
  integrations: [sitemap()],
});

Opsi yang sering dipakai:

• site: domain kanonik, dipakai sitemap dan canonical URL.
• base: awalan path jika situs di-hosting di subfolder.
• output: static, server, atau hybrid.
• integrations: daftar integrasi resmi seperti sitemap.

base: "/blog" misalnya membuat semua rute diawali /blog — berguna saat menempatkan situs di subdirectory hosting.

#Menjalankan Berbagai Environment

Astro membaca astro.config.mjs sekali saat build. Untuk konfigurasi berbeda antar environment, kalian bisa memakai flag --mode pada CLI, misalnya astro build --mode staging, dan membaca mode melalui import.meta.env.MODE di kode.

#Environment Variables dan Runtime Config

#Variabel yang Terlihat di Klien

Variabel environment yang diawali PUBLIC_ bisa diakses dari kode klien dan frontmatter. Simpan di file .env:

PUBLIC_API_URL=https://api.contoh.dev
PUBLIC_GA_ID=G-XXXXXXX
API_SECRET=rahasiabackend

Lalu gunakan di kode:

Memakai env variable

---
const apiUrl = import.meta.env.PUBLIC_API_URL;
---
 
<p>API berjalan di {apiUrl}</p>

import.meta.env.PUBLIC_API_URL hanya membaca variabel berawalan PUBLIC_. Variabel tanpa awalan seperti API_SECRET tersimpan di sisi server saja dan tidak pernah bocor ke bundle klien.

#Keamanan Variabel Rahasia

Ingat aturan penting: semua yang diawali PUBLIC_ ikut terkirim ke browser. Jangan pernah meletakkan API key server di variabel berawalan PUBLIC_. Untuk mode server, variabel tanpa awalan bisa dibaca dari import.meta.env karena kode berjalan di runtime server.

Buat juga file .env.example berisi daftar variabel tanpa nilai asli, dan pastikan .env* masuk ke .gitignore agar rahasia tidak ter-commit.

#Integrasi Plugin dan Adapter

#Memasang Integrasi dengan astro add

Cara paling aman menambahkan integrasi adalah npx astro add, karena perintah ini sekaligus mengupdate astro.config.mjs dan menginstall dependency:

npx astro add sitemap mdx

npx astro add sitemap mdx memasang dua integrasi sekaligus. Setiap integrasi ditambahkan ke array integrations dengan urutan yang menentukan pipeline-nya.

#Adapter untuk Mode Server

Jika project memakai output: "server" atau "hybrid", kalian wajib memilih adapter sesuai platform hosting. Adapter mengubah build agar berjalan di runtime platform tersebut:

• @astrojs/vercel untuk Vercel.
• @astrojs/netlify untuk Netlify.
• @astrojs/cloudflare untuk Cloudflare.
• @astrojs/node untuk server Node.js umum.

Adapter Netlify

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify";
 
export default defineConfig({
  output: "server",
  adapter: netlify(),
});

Pemilihan adapter menentukan cara deployment dan lokasi fungsi serverless — episode 20 akan membahas lebih dalam.

#Build Optimization dan Output Path

#Mengatur Output dan Trailing Slash

Folder output default adalah dist/. Kalian bisa mengubahnya lewat opsi build di astro.config.mjs:

Opsi build kustom

export default defineConfig({
  build: {
    format: "directory",
    inlineStylesheets: "auto",
  },
  trailingSlash: "ignore",
});

• format: "directory" menghasilkan URL tanpa ekstensi, seperti /blog/posts/satu/.
• inlineStylesheets: "auto" menyisipkan CSS kecil langsung ke HTML.
• trailingSlash: "ignore" membiarkan URL dengan dan tanpa slash berjalan.

#Memeriksa Hasil Build

Setelah npm run build, periksa isi dist/. CSS ter-minify, HTML siap layanan, dan aset statis tercopy dari public. Untuk situs statis, folder ini bisa di-upload ke hosting mana pun tanpa proses tambahan.

#Penutup

Episode 8 membekali kalian konfigurasi yang solid: isi dan opsi astro.config.mjs, penggunaan environment variables dengan aturan PUBLIC_, pemasangan integrasi dan adapter, serta optimasi build dan output path.

Inti yang harus dibawa pulang:

• astro.config.mjs mengatur site, base, output, dan integrations.
• Variabel PUBLIC_ terlihat di klien; variabel lain tetap di server.
• import.meta.env adalah cara membaca environment variables.
• npx astro add adalah cara teraman menambah integrasi.
• Adapter wajib dipilih untuk mode server sesuai platform hosting.
• Opsi build mengontrol format URL, CSS, dan folder output.

Di episode 9 selanjutnya kita akan membahas images dan asset optimization: optimasi gambar responsif, manajemen aset dan file statis, lazy loading media, serta cache control dan integrasi CDN. Gambar adalah aset terberat di web — mengoptimalkannya memberi dampak besar.