Astro Framework: Panduan Lengkap 2026

Astro dirancang agar mudah dipelajari oleh orang yang sudah memahami dasar HTML, CSS, dan JavaScript. Pengalaman memakai React, Vue, atau framework lain dapat membantu, tetapi tidak menjadi syarat karena komponen Astro terasa dekat dengan penulisan HTML biasa.

Perangkat utama yang dibutuhkan adalah Node.js, package manager, editor kode, terminal, dan browser modern. Versi Node.js minimum dapat berubah mengikuti rilis Astro, jadi periksa panduan instalasi resmi Astro sebelum memulai proyek produksi.

Periksa apakah Node.js dan npm sudah tersedia:

node --version
npm --version

Kedua perintah tersebut harus menampilkan nomor versi. Jika terminal menampilkan pesan seperti command not found, instal Node.js versi LTS lalu buka ulang terminal.

Beberapa pengetahuan dasar yang akan membantu:

• Struktur dokumen HTML dan penggunaan elemen semantik

• Selector, layout, dan responsive design dengan CSS

• Variabel, array, objek, fungsi, serta module JavaScript

• Perintah dasar terminal seperti cd, mkdir, dan npm

• Konsep import dan export

• Dasar Git untuk menyimpan riwayat perubahan

• Perbedaan kode yang berjalan di server dan di browser

TypeScript tidak wajib, tetapi layak digunakan pada proyek jangka panjang. Astro memiliki dukungan TypeScript sehingga props komponen, data koleksi, dan hasil integrasi dapat diperiksa sebelum aplikasi dijalankan.

Sebelum menulis kode, tentukan jenis situs dan pola perubahan datanya. Keputusan ini membantu memilih antara static generation dan server-side rendering.

Static generation merupakan titik awal yang lebih sederhana. Hasil build dapat disajikan melalui CDN tanpa menjalankan server aplikasi untuk setiap kunjungan.

Server-side rendering sebaiknya ditambahkan ketika terdapat kebutuhan nyata, seperti sesi, cookie, data personal, atau informasi yang harus selalu terbaru. Memilih SSR untuk seluruh situs tanpa alasan jelas dapat menambah biaya operasional dan beban pemeliharaan.

Step 1: Buat proyek Astro dan jalankan server lokal

Astro menyediakan command-line interface untuk membuat proyek baru. Wizard ini menyiapkan struktur direktori, dependency, TypeScript, dan repository Git berdasarkan pilihan saat instalasi.

Jalankan perintah berikut:

npm create astro@latest

Wizard akan meminta nama proyek dan jenis starter. Untuk belajar, pilih starter minimal agar hubungan antara halaman, layout, dan komponen terlihat jelas.

Contoh pilihan awal:

Where should we create your new project?
./belajar-astro

How would you like to start your new project?
A basic, minimal starter

Install dependencies?
Yes

Do you plan to write TypeScript?
Yes

Initialize a new git repository?
Yes

Masuk ke direktori proyek:

cd belajar-astro

Jalankan server pengembangan:

npm run dev

Terminal akan menampilkan alamat lokal, umumnya http://localhost:4321. Buka alamat tersebut melalui browser untuk melihat halaman awal.

Astro memakai development server dengan pembaruan cepat. Saat file sumber disimpan, perubahan biasanya tampil tanpa menjalankan ulang proses secara manual.

Perintah utama yang perlu dikenali meliputi:

npm run dev
npm run build
npm run preview

Fungsinya berbeda:

• npm run dev menjalankan lingkungan pengembangan.

• npm run build membuat keluaran produksi.

• npm run preview menampilkan hasil build secara lokal.

Jalankan build segera setelah proyek dibuat:

Baca juga Apa Itu Seeder Laravel? Fungsi, Cara Pakai & Contohnya

npm run build

Langkah sederhana ini memastikan dependency, konfigurasi, dan lingkungan Node.js bekerja dengan benar sebelum struktur proyek bertambah rumit. Pada proyek statis, hasil build umumnya disimpan di direktori dist/.

Jika Git belum diaktifkan oleh wizard, gunakan:

git init
git add .
git commit -m "Inisialisasi proyek Astro"

Pastikan file .gitignore tidak memasukkan dependency, hasil build, dan rahasia lingkungan:

node_modules/
dist/
.astro/
.env

File .env tidak boleh dikirim ke repository apabila menyimpan token API, kredensial layanan, atau data sensitif lain.

Step 2: Susun halaman, layout, dan komponen

Astro menggunakan file-based routing. File di dalam src/pages/ otomatis menjadi halaman atau endpoint berdasarkan nama dan posisi direktorinya.

Struktur proyek dasar biasanya terlihat seperti berikut:

belajar-astro/
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/
│   ├── components/
│   ├── content/
│   ├── layouts/
│   ├── pages/
│   │   └── index.astro
│   └── styles/
├── astro.config.mjs
├── package.json
└── tsconfig.json

Setiap direktori memiliki fungsi yang berbeda:

• public/ menyimpan aset yang disalin tanpa pemrosesan.

• src/assets/ cocok untuk gambar yang akan dioptimalkan.

• src/components/ berisi unit antarmuka yang dapat digunakan ulang.

• src/content/ menyimpan konten lokal dan koleksi.

• src/layouts/ berisi kerangka halaman bersama.

• src/pages/ menentukan URL situs.

• src/styles/ menyimpan stylesheet global.

• astro.config.mjs memuat konfigurasi dan integrasi.

File src/pages/index.astro menjadi halaman utama. Buat halaman sederhana seperti berikut:

---
const title = "Belajar Astro";
const description = "Situs ringan yang dibuat dengan Astro Framework.";
---

<!doctype html>
<html lang="id">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1"
    />
    <meta name="description" content={description} />
    <title>{title}</title>
  </head>

  <body>
    <main>
      <h1>{title}</h1>
      <p>{description}</p>
    </main>
  </body>
</html>

Bagian di antara tanda --- disebut frontmatter atau component script. Kode tersebut berjalan di server saat build atau ketika permintaan diproses, bergantung pada mode rendering.

Template setelah frontmatter menggunakan sintaks mirip HTML. Nilai JavaScript dapat dimasukkan dengan kurung kurawal, seperti {title}.

Membuat struktur HTML lengkap pada setiap halaman akan menghasilkan pengulangan. Pindahkan elemen bersama ke src/layouts/BaseLayout.astro:

---
interface Props {
  title: string;
  description?: string;
}

const {
  title,
  description = "Situs berbasis konten dengan Astro."
} = Astro.props;
---

<!doctype html>
<html lang="id">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1"
    />
    <meta name="description" content={description} />
    <title>{title}</title>
  </head>

  <body>
    <header>
      <nav aria-label="Navigasi utama">
        <a href="/">Beranda</a>
        <a href="/artikel">Artikel</a>
        <a href="/tentang">Tentang</a>
      </nav>
    </header>

    <main>
      <slot />
    </main>

    <footer>
      <p>Belajar Astro</p>
    </footer>
  </body>
</html>

Elemen <slot /> menjadi tempat konten halaman dimasukkan. Halaman utama sekarang dapat disederhanakan:

---
import BaseLayout from "../layouts/BaseLayout.astro";
---

<BaseLayout
  title="Belajar Astro"
  description="Situs ringan yang dibuat dengan Astro Framework."
>
  <h1>Belajar Astro</h1>
  <p>Halaman ini dikirim sebagai HTML tanpa runtime klien tambahan.</p>
</BaseLayout>

Buat src/pages/tentang.astro:

---
import BaseLayout from "../layouts/BaseLayout.astro";
---

<BaseLayout title="Tentang">
  <h1>Tentang</h1>
  <p>Halaman ini tersedia melalui rute /tentang.</p>
</BaseLayout>

Komponen antarmuka yang berulang dapat disimpan dalam src/components/. Contoh kartu artikel:

---
interface Props {
  title: string;
  description: string;
  href: string;
}

const { title, description, href } = Astro.props;
---

<article class="card">
  <h2>
    <a href={href}>{title}</a>
  </h2>
  <p>{description}</p>
</article>

<style>
  .card {
    padding: 1.25rem;
    border: 1px solid #d9dee7;
    border-radius: 0.75rem;
  }

  .card h2 {
    margin-top: 0;
  }
</style>

CSS di dalam komponen Astro bersifat scoped secara default. Aturan .card tidak langsung memengaruhi komponen lain yang memakai nama kelas serupa.

Step 3: Kelola artikel dengan Content Collections

Menulis setiap artikel sebagai halaman .astro akan membuat metadata dan struktur sulit dikelola. Content Collections menyediakan cara teratur untuk menyimpan Markdown, MDX, atau data eksternal dengan validasi skema.

Buat struktur berikut:

src/
├── content/
│   └── blog/
│       ├── memulai-astro.md
│       └── astro-islands.md
└── content.config.ts

Isi src/content.config.ts:

import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";

const blog = defineCollection({
  loader: glob({
    pattern: "**/*.{md,mdx}",
    base: "./src/content/blog",
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog };

Skema tersebut memastikan setiap artikel memiliki judul, deskripsi, tanggal, status draft, dan daftar tag. Kesalahan metadata dapat ditemukan saat development atau build, bukan setelah konten diterbitkan.

Buat src/content/blog/memulai-astro.md:

Baca juga 9Router — Gateway Proxy AI Lokal Open Source Gratis

---
title: "Memulai Proyek Astro"
description: "Langkah dasar membuat situs dengan Astro Framework."
pubDate: 2026-07-20
draft: false
tags:
  - astro
  - web-development
---

Astro merender konten menjadi HTML dan memuat JavaScript hanya
ketika sebuah bagian memerlukan interaktivitas.

## Struktur proyek

Halaman disimpan di `src/pages`, sedangkan komponen dapat diletakkan
di `src/components`.

Buat halaman daftar artikel di src/pages/artikel/index.astro:

---
import { getCollection } from "astro:content";
import BaseLayout from "../../layouts/BaseLayout.astro";
import ArticleCard from "../../components/ArticleCard.astro";

const posts = (await getCollection("blog", ({ data }) => !data.draft))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---

<BaseLayout
  title="Artikel Astro"
  description="Kumpulan panduan Astro Framework."
>
  <h1>Artikel Astro</h1>

  <div class="article-list">
    {
      posts.map((post) => (
        <ArticleCard
          title={post.data.title}
          description={post.data.description}
          href={`/artikel/${post.id}/`}
        />
      ))
    }
  </div>
</BaseLayout>

Filter pada getCollection() mengecualikan artikel draft. Fungsi sort() mengurutkan artikel berdasarkan tanggal publikasi terbaru.

Selanjutnya, buat dynamic route src/pages/artikel/[...id].astro:

---
import { getCollection, render } from "astro:content";
import BaseLayout from "../../layouts/BaseLayout.astro";

export async function getStaticPaths() {
  const posts = await getCollection("blog", ({ data }) => !data.draft);

  return posts.map((post) => ({
    params: { id: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---

<BaseLayout
  title={post.data.title}
  description={post.data.description}
>
  <article>
    <header>
      <h1>{post.data.title}</h1>
      <time datetime={post.data.pubDate.toISOString()}>
        {post.data.pubDate.toLocaleDateString("id-ID")}
      </time>
    </header>

    <Content />
  </article>
</BaseLayout>

getStaticPaths() menentukan halaman yang perlu dibuat saat build. Setiap entri koleksi menghasilkan satu URL berdasarkan ID konten.

API Content Collections dapat berubah saat Astro diperbarui. Cocokkan implementasi dengan dokumentasi Content Collections ketika membuat proyek baru atau melakukan upgrade.

Step 4: Tambahkan interaktivitas dengan Astro Islands

Sebagian besar elemen situs tidak membutuhkan hydration. Judul, artikel, daftar tautan, breadcrumb, dan kartu statis dapat dikirim sebagai HTML biasa.

Astro Island adalah komponen interaktif yang dihidrasi secara terpisah, sementara bagian lain halaman tetap berupa HTML statis.

Interaksi sederhana dapat dibuat tanpa React atau Vue. Contoh pengalih tema:

<button id="theme-toggle" type="button" aria-pressed="false">
  Ganti tema
</button>

<script>
  const button = document.querySelector("#theme-toggle");

  button?.addEventListener("click", () => {
    const isDark = document.documentElement.classList.toggle("dark");
    button.setAttribute("aria-pressed", String(isDark));
  });
</script>

Script tersebut berjalan di browser. Sebaliknya, kode frontmatter berjalan di server dan tidak dapat memakai document, window, atau localStorage.

Framework UI diperlukan ketika komponen memiliki state, validasi, atau alur interaksi yang lebih kompleks. Tambahkan integrasi React:

npx astro add react

Buat src/components/SearchArticles.jsx:

import { useMemo, useState } from "react";

export default function SearchArticles({ articles }) {
  const [query, setQuery] = useState("");

  const results = useMemo(() => {
    const keyword = query.trim().toLowerCase();

    if (!keyword) return articles;

    return articles.filter((article) =>
      article.title.toLowerCase().includes(keyword)
    );
  }, [articles, query]);

  return (
    <section aria-labelledby="search-heading">
      <h2 id="search-heading">Cari artikel</h2>

      <label>
        Kata kunci
        <input
          type="search"
          value={query}
          onChange={(event) => setQuery(event.target.value)}
        />
      </label>

      <ul>
        {results.map((article) => (
          <li key={article.href}>
            <a href={article.href}>{article.title}</a>
          </li>
        ))}
      </ul>
    </section>
  );
}

Gunakan komponen pada halaman Astro:

---
import SearchArticles from "../../components/SearchArticles.jsx";

const articles = [
  {
    title: "Memulai Proyek Astro",
    href: "/artikel/memulai-astro/",
  },
  {
    title: "Memahami Astro Islands",
    href: "/artikel/astro-islands/",
  },
];
---

<SearchArticles articles={articles} client:load />

Direktif client:load mengaktifkan komponen segera. Pilih direktif lain jika komponen tidak harus aktif sejak awal.

Jangan menambahkan client:load ke setiap komponen React. Komponen tanpa direktif client: tetap dapat dirender menjadi HTML tanpa mengirimkan runtime React ke browser.

Step 5: Atur metadata, gambar, dan aksesibilitas

Astro memberi dasar performa yang baik, tetapi SEO tetap bergantung pada struktur konten, metadata, internal link, kualitas halaman, dan pengalaman pengguna. HTML statis tidak otomatis memperbaiki judul yang kabur atau gambar yang terlalu besar.

Buat komponen metadata src/components/SEO.astro:

---
interface Props {
  title: string;
  description: string;
  canonical?: URL;
  image?: URL;
  type?: "website" | "article";
}

const {
  title,
  description,
  canonical = Astro.url,
  image,
  type = "website",
} = Astro.props;
---

<title>{title}</title>
<meta name="description" content={description} />
<link rel="canonical" href={canonical} />

<meta property="og:type" content={type} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:url" content={canonical} />

{image && <meta property="og:image" content={image} />}

<meta name="twitter:card" content="summary_large_image" />

Masukkan komponen tersebut ke bagian <head> pada layout. Setiap halaman perlu memiliki judul dan deskripsi yang spesifik, bukan metadata identik untuk seluruh situs.

Untuk gambar lokal, simpan file di src/assets/ lalu gunakan komponen Image:

---
import { Image } from "astro:assets";
import heroImage from "../assets/hero.jpg";
---

<Image
  src={heroImage}
  alt="Tampilan struktur proyek Astro di editor kode"
  width={1200}
  quality={80}
/>

Komponen gambar membantu menghasilkan dimensi yang jelas dan aset yang lebih sesuai untuk web. Atribut alt harus menjelaskan informasi yang dibawa gambar.

Gunakan alt="" untuk gambar dekoratif. Jangan menghapus atribut tersebut karena pembaca layar perlu mengetahui bahwa gambar dapat diabaikan.

HTML semantik juga perlu dijaga:

Baca juga Img2threejs: Foto Jadi Model 3D Prosedural Three.js

• Gunakan <nav> untuk navigasi.

• Gunakan <main> untuk konten utama.

• Gunakan <article> untuk konten mandiri.

• Gunakan <section> untuk kelompok konten bertema.

• Gunakan <button> untuk tindakan.

• Gunakan <a> untuk perpindahan lokasi.

Jaga urutan heading tetap logis. Hindari memilih level heading berdasarkan ukuran visual karena tampilan dapat diatur melalui CSS.

Step 6: Ambil data dan pilih mode rendering

Astro dapat mengambil data dari API atau headless CMS melalui fetch() di frontmatter. Waktu eksekusinya bergantung pada mode rendering.

Pada static generation, request berjalan saat build:

---
import BaseLayout from "../layouts/BaseLayout.astro";

const response = await fetch("https://api.example.com/products");

if (!response.ok) {
  throw new Error(`API mengembalikan status ${response.status}`);
}

const products = await response.json();
---

<BaseLayout title="Katalog Produk">
  <h1>Katalog Produk</h1>

  <ul>
    {
      products.map((product) => (
        <li>
          <h2>{product.name}</h2>
          <p>{product.description}</p>
        </li>
      ))
    }
  </ul>
</BaseLayout>

Data tersebut tidak berubah sampai build berikutnya. Pola ini cocok untuk data publik yang diperbarui melalui proses publikasi terjadwal.

Data langsung atau respons berdasarkan sesi membutuhkan server-side rendering. Setelah adapter platform dipasang, rute tertentu dapat memakai:

---
export const prerender = false;

const response = await fetch("https://api.example.com/live-stock");

if (!response.ok) {
  throw new Error("Inventaris gagal dimuat");
}

const stock = await response.json();
---

<p>Stok tersedia: {stock.available}</p>

Jangan mengirim seluruh objek API ke komponen klien. Pilih hanya field yang aman:

---
const privateProducts = await loadProducts();

const publicProducts = privateProducts.map((product) => ({
  id: product.id,
  name: product.name,
  price: product.publicPrice,
}));
---

<ProductList products={publicProducts} client:visible />

Token API harus disimpan dalam variabel lingkungan dan hanya dibaca oleh kode server. Jangan menempatkan kredensial dalam props island, URL, script browser, atau repository.

Step 7: Uji build dan terbitkan situs Astro

Pengujian produksi perlu dilakukan sebelum deployment karena development server tidak selalu menampilkan masalah yang sama dengan proses build.

Jalankan:

npm run build
npm run preview

Periksa seluruh rute melalui versi preview. Fokus pada halaman dinamis, gambar, metadata, tautan internal, halaman 404, dan komponen yang memakai direktif client:.

Untuk proyek statis, direktori dist/ dapat diterbitkan melalui layanan static hosting. Banyak platform mendeteksi Astro secara otomatis.

Konfigurasi umum deployment statis:

Push proyek ke repository:

git add .
git commit -m "Siapkan deployment Astro"
git branch -M main
git remote add origin https://github.com/nama-akun/belajar-astro.git
git push -u origin main

Server-side rendering membutuhkan adapter yang sesuai dengan platform. Untuk Cloudflare, integrasi dapat ditambahkan melalui:

npx astro add cloudflare

Setelah adapter terpasang, jalankan build lagi untuk menemukan dependency atau API yang tidak kompatibel dengan runtime target. Ikuti panduan deployment resmi Astro karena konfigurasi adapter dapat berubah mengikuti versi framework dan platform.

Setelah situs terbit, periksa:

1. Semua halaman utama dapat dibuka.

2. Dynamic route menghasilkan URL yang benar.

3. Gambar dan font tidak gagal dimuat.

4. Canonical URL memakai domain produksi.

5. Island interaktif bekerja melalui keyboard.

6. Tidak ada token pada source HTML.

7. Halaman 404 memberikan status yang benar.

8. Log server tidak memuat error berulang.

9. Formulir menangani kegagalan jaringan.

10. Tampilan tetap terbaca pada layar kecil.

Kesalahan umum saat menggunakan Astro Framework

Astro terasa sederhana karena sintaksnya dekat dengan HTML, tetapi beberapa kesalahan sering muncul ketika pola dari aplikasi client-side diterapkan tanpa penyesuaian. Masalah yang paling umum berkaitan dengan konteks eksekusi, hydration berlebihan, pemilihan rendering, dan pengelolaan aset.

Mengakses API browser dari frontmatter

Frontmatter berjalan di server. Kode berikut akan gagal:

---
const theme = localStorage.getItem("theme");
---

localStorage hanya tersedia di browser. Pindahkan akses tersebut ke script klien:

<script>
  const theme = localStorage.getItem("theme");

  if (theme === "dark") {
    document.documentElement.classList.add("dark");
  }
</script>

Log dari frontmatter muncul di terminal atau log server. Log dari script klien muncul di konsol browser. Perbedaan lokasi tersebut membantu mengenali tempat kode dijalankan.

Baca juga OpenCode Free: Agen AI Coding Gratis dan Open Source

Menghidrasi setiap komponen

Komponen React atau Vue tidak selalu membutuhkan direktif client:. Tanpa direktif tersebut, Astro masih dapat merender komponen menjadi HTML.

Menambahkan client:load pada semua komponen akan meningkatkan jumlah JavaScript, waktu parsing, dan pekerjaan browser. Hasilnya dapat bertentangan dengan alasan utama memilih Astro.

Gunakan hydration berdasarkan kebutuhan perilaku, bukan berdasarkan jenis file komponen.

Kartu produk statis tidak memerlukan hydration. Tombol keranjang yang menyimpan state memerlukannya.

Pilih client:visible untuk komponen di bawah area awal halaman. Gunakan client:idle untuk fitur pendukung dan client:load hanya untuk kontrol yang harus segera aktif.

Mengaktifkan SSR untuk seluruh situs

SSR memang berguna, tetapi membawa kebutuhan runtime, cache, observabilitas, dan penanganan error. Blog yang berubah saat artikel baru terbit biasanya cukup memakai static generation dengan build otomatis.

Pisahkan halaman berdasarkan kebutuhan data:

• Halaman editorial dapat dibuat statis.

• Data personal dapat dirender di server.

• Inventaris langsung dapat memakai rute server.

• Komponen klien dapat mengambil data setelah halaman dimuat jika pengalaman pengguna tetap terjaga.

Pendekatan campuran membuat bagian statis tetap mudah di-cache tanpa menghalangi kebutuhan dinamis.

Menyimpan gambar besar di public/

Aset dalam public/ disalin apa adanya. Gambar berukuran beberapa megabyte akan tetap dikirim dalam ukuran tersebut apabila tidak diproses sebelumnya.

Simpan gambar konten di src/assets/ jika optimasi Astro diperlukan. Tentukan ukuran yang masuk akal, berikan atribut alt, dan hindari memuat gambar resolusi tinggi untuk ruang tampilan kecil.

Gambar utama di bagian atas halaman mungkin perlu diprioritaskan. Gambar yang jauh di bawah halaman dapat memakai lazy loading.

Mencampur terlalu banyak framework UI

Astro mendukung React, Vue, Svelte, Preact, dan Solid, tetapi kemampuan itu bukan alasan untuk memakai semuanya. Setiap framework membawa dependency, pola state, cara pengujian, dan runtime sendiri.

Tetapkan satu framework klien utama. Gunakan komponen .astro untuk struktur statis dan tambahkan framework kedua hanya jika ada kebutuhan yang tidak dapat dipenuhi secara wajar oleh pilihan utama.

Pada proses migrasi, catat komponen yang masih memakai runtime lama. Dokumentasi tersebut memudahkan penghapusan dependency setelah migrasi selesai.

Mengabaikan kegagalan API saat build

Request API dapat gagal karena jaringan, autentikasi, rate limit, atau perubahan format data. Build tidak boleh menganggap semua respons selalu berhasil.

Periksa status respons:

const response = await fetch(endpoint);

if (!response.ok) {
  throw new Error(`Permintaan gagal: ${response.status}`);
}

const data = await response.json();

Validasi bentuk data sebelum dipakai. Untuk konten penting, tentukan apakah build harus gagal, memakai cache lama, atau menampilkan fallback.

Jangan menyembunyikan error dengan data kosong tanpa pencatatan. Halaman yang berhasil dibangun tetapi kehilangan seluruh konten sering lebih sulit dideteksi daripada build yang gagal dengan pesan jelas.

Tidak menjalankan build sebelum push

Kode yang berjalan pada development server belum tentu lolos build produksi. Dynamic route, import gambar, skema konten, dan variabel lingkungan sering baru menunjukkan masalah saat npm run build.

Tambahkan pemeriksaan berikut sebelum commit besar:

npm run build
npm run preview

Pada repository tim, jalankan build melalui continuous integration untuk setiap pull request. Pemeriksaan otomatis membantu menemukan kesalahan sebelum perubahan masuk ke branch produksi.

Baca juga ClinePass: Langganan Model Open Weight untuk Coding

Menganggap Astro otomatis menjamin SEO

Astro dapat mengirimkan HTML lengkap dan mengurangi JavaScript klien, tetapi kualitas SEO tetap bergantung pada implementasi. Judul yang tidak jelas, konten tipis, tautan rusak, dan struktur heading buruk tidak diperbaiki oleh framework.

Periksa setiap halaman untuk memastikan:

• Judul menggambarkan topik dengan jelas.

• Meta description sesuai isi.

• Canonical URL benar.

• Heading mengikuti urutan logis.

• Gambar memiliki teks alternatif.

• Internal link menghubungkan konten terkait.

• Halaman dapat dipakai dengan keyboard.

• Konten utama hadir dalam HTML awal.

Langkah berikutnya adalah membuat satu proyek minimal dengan npm create astro@latest, lalu menyelesaikan satu halaman statis sampai berhasil melewati npm run build. Setelah fondasi tersebut bekerja, tambahkan hanya satu fitur interaktif dan ukur JavaScript yang benar-benar dikirim ke browser.

Rawat performa dan stabilitas setelah deployment

Situs yang sudah terbit tetap perlu dipantau karena ukuran aset, dependency, konten baru, dan script pihak ketiga dapat berubah dari waktu ke waktu. Astro mengurangi JavaScript secara default, tetapi keputusan setelah deployment tetap menentukan apakah halaman bertahan ringan saat proyek tumbuh.

Tetapkan anggaran performa

Anggaran performa memberi batas yang dapat diperiksa setiap kali fitur baru ditambahkan. Batas tidak harus rumit, tetapi perlu mencakup aset yang paling sering memperlambat halaman.

Contoh anggaran awal:

Nilai tersebut dapat disesuaikan dengan kebutuhan situs dan kondisi pengguna. Situs yang banyak diakses melalui jaringan seluler perlu memakai batas lebih ketat daripada portal internal pada jaringan cepat.

Gunakan panel Network di browser untuk memeriksa transfer size, waktu respons, dan request yang memblokir rendering. Data lapangan juga perlu diprioritaskan ketika trafik sudah cukup karena perangkat nyata tidak selalu memberikan hasil yang sama dengan pengujian lokal.

Penjelasan tentang metrik utama tersedia dalam panduan Core Web Vitals dari web.dev. Fokus pada perubahan yang memengaruhi pengalaman pengguna, bukan mengejar skor tanpa memahami penyebabnya.

Audit script pihak ketiga

Analytics, widget percakapan, iklan, formulir eksternal, dan pemutar video dapat menambah lebih banyak JavaScript daripada kode aplikasi. Script semacam ini juga dapat membuat koneksi ke banyak domain dan menunda interaksi awal.

Catat setiap script pihak ketiga beserta tujuan dan pemiliknya:

Nama: Analytics utama
Tujuan: Mengukur kunjungan dan konversi
Pemilik: Tim pemasaran
Dimuat pada: Seluruh halaman
Strategi: defer
Tanggal evaluasi: 2026-08-01

Hapus integrasi yang tidak lagi dipakai. Jangan memuat widget pada semua rute jika hanya dibutuhkan pada satu halaman.

Elemen seperti video eksternal dapat memakai placeholder gambar dan baru memuat pemutar setelah interaksi. Strategi tersebut mengurangi request awal tanpa menghapus fungsi utama.

Perbarui dependency secara bertahap

Pembaruan Astro, adapter, dan integrasi sebaiknya dilakukan dalam perubahan kecil. Menggabungkan upgrade framework, penggantian CMS, dan perubahan desain dalam satu pull request membuat sumber error sulit ditemukan.

Sebelum upgrade:

1. Pastikan branch utama dapat dibangun.

2. Simpan perubahan yang belum selesai.

3. Baca catatan rilis dan panduan migrasi.

4. Buat branch khusus.

5. Perbarui satu kelompok dependency.

6. Jalankan pemeriksaan tipe, test, dan build.

7. Periksa halaman penting melalui preview deployment.

Riwayat rilis dapat diperiksa melalui halaman rilis Astro di GitHub. Perhatikan perubahan pada Content Collections, adapter, konfigurasi gambar, dan API rendering karena bagian tersebut sering terhubung langsung dengan proses build.

Hindari memperbarui dependency hanya berdasarkan nomor versi terbaru. Pastikan versi Node.js, adapter hosting, dan integrasi UI tetap kompatibel.

Gunakan perintah berikut untuk melihat paket yang tertinggal:

npm outdated

Setelah pembaruan dilakukan, instal dependency dari kondisi bersih:

rm -rf node_modules
npm install
npm run build

Pada lingkungan continuous integration, npm ci lebih tepat ketika lockfile tersedia karena instalasi mengikuti versi yang sudah dicatat.

Baca juga Kiro Dev: IDE Agentic AWS untuk Spec-Driven Development

Pisahkan konfigurasi berdasarkan lingkungan

Nilai untuk development, preview, dan production sering berbeda. Endpoint CMS uji tidak seharusnya dipakai oleh situs produksi, sedangkan kredensial produksi tidak perlu tersedia pada mesin lokal setiap anggota tim.

Gunakan penamaan variabel yang jelas:

CONTENT_API_URL=https://cms.example.com
CONTENT_API_TOKEN=nilai-rahasia
PUBLIC_ANALYTICS_ID=analytics-publik

Variabel yang diekspos ke browser harus dianggap publik. Jangan memakai awalan publik pada token, password, private key, atau kredensial layanan.

Buat validasi saat aplikasi dimulai agar build berhenti ketika variabel wajib tidak tersedia:

const apiUrl = import.meta.env. CONTENT_API_URL;

if (!apiUrl) {
  throw new Error("CONTENT_API_URL belum diatur");
}

Atur nilai rahasia melalui dashboard platform hosting. File .env lokal tetap berada di .gitignore.

Buat alur editorial yang aman

Content Collections dapat menjaga format metadata, tetapi proses publikasi tetap membutuhkan aturan. Tentukan siapa yang dapat mengubah skema, bagaimana draft diperiksa, dan kapan build produksi dijalankan.

Status konten dapat dibuat lebih jelas dengan field tambahan:

status: z.enum(["draft", "review", "published"]),

Filter halaman publik berdasarkan status:

const posts = await getCollection(
  "blog",
  ({ data }) => data.status === "published"
);

Preview deployment dapat dipakai untuk memeriksa artikel yang masih berstatus review. Tim editorial dapat mengecek heading, gambar, tautan, dan tampilan seluler sebelum konten diterbitkan.

Tanggal pembaruan juga perlu dipisahkan dari tanggal publikasi. Perubahan kecil seperti koreksi ejaan tidak selalu perlu mengubah tanggal, sedangkan revisi substansial sebaiknya terlihat oleh pengunjung.

Pantau tautan dan rute lama

Perubahan slug dapat memutus internal link dan trafik dari mesin pencari. Simpan daftar redirect ketika struktur URL diubah.

Contoh pemetaan:

/artikel/astro-dasar/ -> /artikel/memulai-astro/
/panduan/islands/ -> /artikel/astro-islands/

Pemeriksaan tautan dapat dijalankan setelah build untuk menemukan URL internal yang mengarah ke halaman tidak tersedia. Audit juga perlu mencakup tautan eksternal karena sumber pihak ketiga dapat dipindahkan atau dihapus.

Untuk setiap perubahan rute, periksa hal berikut:

• URL lama memiliki redirect permanen.

• Canonical mengarah ke URL baru.

• Sitemap tidak lagi memuat URL lama.

• Internal link sudah diperbarui.

• Redirect tidak membentuk rantai.

• Halaman tujuan memberikan status 200.

• Halaman yang dihapus tanpa pengganti memberikan status 404 atau 410.

Tambahkan pengujian otomatis untuk alur penting

Build yang berhasil belum membuktikan bahwa navigasi, formulir, dan island interaktif bekerja sesuai kebutuhan. Pengujian otomatis perlu memeriksa perilaku yang benar-benar dialami pengguna, terutama pada rute utama dan fitur yang bergantung pada JavaScript klien.

Pisahkan jenis pengujian berdasarkan risiko

Tidak semua komponen memerlukan pengujian browser lengkap. Fungsi pemetaan data dapat diuji sebagai unit, sedangkan proses pencarian atau pengiriman formulir lebih tepat diperiksa melalui browser.

Gunakan pembagian berikut:

Prioritaskan alur yang berpengaruh pada publikasi, pendapatan, atau akses ke konten. Halaman dekoratif sederhana tidak membutuhkan jumlah test yang sama dengan checkout atau formulir pendaftaran.

Uji halaman melalui hasil build

Pengujian end-to-end sebaiknya dijalankan terhadap hasil produksi lokal, bukan hanya development server. Cara ini membantu menemukan perbedaan routing, aset, dan hydration yang baru muncul setelah build.

Jalankan build dan preview:

Baca juga Codex CLI dari OpenAI: Panduan Lengkap Ngoding di Terminal

npm run build
npm run preview

Tool seperti Playwright dapat membuka situs melalui browser nyata dan memeriksa perilaku halaman. Contoh pengujian sederhana:

import { test, expect } from "@playwright/test";

test("halaman artikel dapat dibuka", async ({ page }) => {
  await page.goto("/artikel/memulai-astro/");

  await expect(
    page.getByRole("heading", {
      level: 1,
      name: "Memulai Proyek Astro",
    })
  ).toBeVisible();

  await expect(page.locator("article")).toBeVisible();
});

Tambahkan pengujian untuk island yang memakai hydration:

test("pencarian menyaring daftar artikel", async ({ page }) => {
  await page.goto("/artikel/");

  const input = page.getByRole("searchbox", {
    name: "Kata kunci",
  });

  await input.fill("islands");

  await expect(
    page.getByRole("link", {
      name: "Memahami Astro Islands",
    })
  ).toBeVisible();

  await expect(
    page.getByRole("link", {
      name: "Memulai Proyek Astro",
    })
  ).toBeHidden();
});

Pengujian tersebut memeriksa hasil yang terlihat, bukan detail implementasi React atau Astro. Perubahan internal komponen tidak akan merusak test selama perilaku pengguna tetap sama.

Periksa kondisi tanpa JavaScript

Karena Astro mengutamakan HTML, konten utama seharusnya tetap tersedia ketika JavaScript gagal dimuat. Kondisi ini dapat terjadi akibat jaringan tidak stabil, ekstensi browser, kesalahan script, atau pemblokiran sumber pihak ketiga.

Matikan JavaScript untuk beberapa pengujian lalu periksa:

• Judul dan isi artikel tetap terlihat.

• Navigasi berbasis tautan masih berfungsi.

• Informasi produk tetap dapat dibaca.

• Pesan penting tidak hanya dibuat oleh komponen klien.

• Formulir memiliki fallback jika fungsi utama mendukungnya.

• Tautan menuju halaman alternatif tersedia untuk fitur kompleks.

Island dapat meningkatkan pengalaman, tetapi tidak seharusnya menyembunyikan konten inti yang sudah tersedia dari server.

Siapkan halaman error yang berguna

Buat halaman 404.astro untuk URL yang tidak ditemukan. Isinya perlu membantu pengunjung kembali ke bagian yang relevan, bukan hanya menampilkan kode status.

---
import BaseLayout from "../layouts/BaseLayout.astro";
---

<BaseLayout
  title="Halaman tidak ditemukan"
  description="Alamat yang dibuka tidak tersedia."
>
  <h1>Halaman tidak ditemukan</h1>
  <p>Alamat mungkin berubah atau konten sudah dihapus.</p>
  <a href="/">Kembali ke beranda</a>
</BaseLayout>

Pada proyek SSR, siapkan penanganan error untuk kegagalan API dan respons server. Pesan untuk pengguna tidak perlu memuat stack trace, token, path internal, atau detail infrastruktur.

Log server tetap harus menyimpan konteks yang berguna, seperti nama rute, status layanan eksternal, dan waktu kejadian. Hindari mencatat password, cookie sesi, token autentikasi, atau isi formulir sensitif.

Tambahkan pemeriksaan keamanan dasar

Situs statis memiliki permukaan serangan lebih kecil daripada aplikasi server penuh, tetapi script pihak ketiga dan konten eksternal tetap perlu dikendalikan. Content Security Policy dapat membatasi sumber script, style, gambar, dan koneksi jaringan yang diizinkan.

Penjelasan teknis mengenai kebijakan tersebut tersedia pada panduan Content Security Policy dari MDN. Mulai dengan mode pelaporan jika situs sudah memakai banyak integrasi agar sumber yang masih diperlukan dapat diidentifikasi sebelum pemblokiran diterapkan.

Checklist pengujian sebelum perubahan masuk ke produksi:

• Build selesai tanpa error.

• Test unit dan end-to-end lulus.

• Rute utama memberikan status yang benar.

• Konten inti terlihat tanpa JavaScript.

• Island aktif sesuai direktif hydration.

• Formulir menampilkan kondisi sukses dan gagal.

• Halaman 404 dapat dinavigasi dengan keyboard.

• Log tidak menyimpan data sensitif.

• Header keamanan aktif pada domain produksi.

• Preview deployment diperiksa pada layar kecil.

Kesimpulan

Astro Framework menawarkan cara praktis untuk membangun situs berbasis konten tanpa mengirimkan JavaScript yang tidak diperlukan. Komponen statis, Content Collections, Astro Islands, pilihan rendering per rute, dan dukungan beberapa framework memberi ruang untuk menambah fitur tanpa mengorbankan struktur yang ringan.

Hasil terbaik tetap bergantung pada keputusan teknis yang disiplin. Hydration perlu dibatasi, gambar harus dioptimalkan, data sensitif tetap berada di server, dan setiap perubahan perlu melewati build, pengujian, serta pemeriksaan keamanan.

Mulai dengan proyek kecil melalui panduan resmi Astro, selesaikan satu halaman statis, lalu tambahkan interaktivitas hanya ketika benar-benar dibutuhkan. Situs yang cepat lebih mudah dibangun ketika HTML menjadi standar awal dan JavaScript menjadi pilihan yang terukur.

Referensi

Docs. (2026). Getting started.

GitHub. (2026). Withastro/Astro: The web framework for content-driven websites.

GitHub. (2026). Astro.

Dev. (2026). First impressions of Astro: What I liked and disliked.

Baca juga CodeBuddy: Editor Kode AI untuk Coding Lebih Cepat

Blog. (2026). Astro is joining Cloudflare.

Apatero. (2026). Astro Web Framework Guide 2025.

Vercel. (2026). What is Astro? How the content-first framework works.

TutorialsPoint. (2026). Astro JS Tutorial.

Strapi. (2026). What is Astro and Why Use It.