Troubleshooting Lengkap: Membangun Web Portofolio Jamstack (Astro) & Mengatasi Error Vercel

Peralihan menuju arsitektur Jamstack (JavaScript, APIs, dan Markup) menggunakan Astro dan Tailwind CSS menawarkan performa tinggi dan keamanan absolut tanpa database. Namun, dalam praktiknya, kita sering dihadapkan pada masalah rantai dependensi (dependency tree), seperti konflik versi antara Astro dan modul integrasi Tailwind, penyesuaian fungsi globbing, hingga kegagalan deployment (Deployment Failed) di lingkungan Vercel. Artikel ini mendokumentasikan langkah strategis untuk merancang web portofolio dinamis sekaligus mengatasi berbagai hambatan teknis tersebut.

Langkah 1: Inisialisasi dan Penanganan Konflik Dependensi (ERESOLVE)

Saat menambahkan Tailwind CSS, NPM sering memunculkan error ERESOLVE akibat ketidakcocokan versi peer dependency (khususnya antara Astro v7+ dan ekosistem Tailwind versi terbaru). Untuk menstabilkan environment pengembangan, kita secara eksplisit memanggil Tailwind versi 3 dan memaksa NPM untuk mengabaikan peringatan tersebut.

Jalankan perintah instalasi berikut dengan menggunakan flag legacy:

npm install @astrojs/tailwind tailwindcss@3 @tailwindcss/typography --legacy-peer-deps
npx astro add tailwind

Langkah 2: Konfigurasi Tipografi dan Desain Premium

Untuk memberikan tampilan layaknya publikasi korporat (Charcoal dan Gold), kita perlu menyematkan plugin tipografi ke dalam konfigurasi Tailwind. Ini menjamin semua teks dari file Markdown dirender secara elegan.

Modifikasi file tailwind.config.mjs di direktori utama (root):

/** @type {import('tailwindcss').Config} */
import typography from '@tailwindcss/typography';

export default {
	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
	theme: {
		extend: {
			colors: {
				charcoal: { 900: '#121212', 800: '#1E1E1E', 700: '#2C2C2C' },
				gold: { DEFAULT: '#D4AF37', dark: '#B5952F', light: '#F3E5AB' }
			},
			fontFamily: {
				sans: ['Inter', 'sans-serif'],
				heading: ['Montserrat', 'sans-serif'],
			}
		},
	},
	plugins: [typography],
}

Langkah 3: Migrasi Fungsi Globbing untuk Daftar Artikel Dinamis

Versi terbaru Astro telah meninggalkan fungsi lawas Astro.glob(). Hal ini memicu error “Astro.glob is not a function” saat sistem mencoba menarik daftar file Markdown. Solusi standar industri saat ini adalah beralih ke fitur globbing bawaan Vite.

Gunakan import.meta.glob pada file daftar blog Anda (src/pages/blog/index.astro):

---
import BaseLayout from '../../layouts/BaseLayout.astro';
// Mengambil data seluruh artikel Markdown secara sinkron (eager)
const allPosts = Object.values(import.meta.glob('./*.md', { eager: true }));
---
<!-- Logika mapping artikel di sini -->
<div class="grid grid-cols-1 md:grid-cols-2 gap-8">
    {allPosts.map((post: any) => (
        <a href={post.url}>
            <h2>{post.frontmatter?.title}</h2>
        </a>
    ))}
</div>

Langkah 4: Membuat Modul Kalkulasi Kategori Dinamis

Untuk meningkatkan fungsionalitas UI, kita merancang sidebar yang mampu menghitung jumlah artikel berdasarkan kategorinya secara otomatis. Proses iterasi membaca setiap frontmatter dan menjumlahkannya.

Sisipkan skrip logika ini di dalam src/layouts/BlogLayout.astro:

const allPosts = Object.values(import.meta.glob('../pages/blog/*.md', { eager: true }));
const categoryCounts = {};

allPosts.forEach((post: any) => {
    const category = post.frontmatter?.category;
    if (category) {
        categoryCounts[category] = (categoryCounts[category] || 0) + 1;
    }
});

Langkah 5: Mengatasi Kegagalan Deployment di Vercel via .npmrc

Hambatan terbesar muncul saat proses Continuous Deployment ke Vercel gagal total akibat error npm install dengan kode 1. Hal ini terjadi karena server build Vercel menggunakan perintah instalasi standar yang menolak peer dependencies bermasalah. Mengubah settings melalui dashboard GUI Vercel terkadang tidak persisten jika melibatkan cache.

Solusi absolutnya adalah melakukan modifikasi pada level kode sumber dengan mendaftarkan aturan instalasi (NPM runtime configuration).

Buat file baru bernama .npmrc di direktori terluar proyek dan isi dengan konfigurasi mutlak berikut:

legacy-peer-deps=true

Langkah 6: Eksekusi Otomatisasi (CI/CD) ke Vercel

Setelah file konfigurasi .npmrc tersimpan, kita hanya perlu menyerahkan seluruh proses pengunggahan kode ke repositori. Vercel akan otomatis mendeteksi konfigurasi tersebut.

Jalankan pengiriman basis kode menggunakan perintah version control:

git add .
git commit -m "Fix dependensi deployment dengan .npmrc & perbaikan fitur blog"
git push origin main

Melalui fondasi arsitektur Jamstack yang dikombinasikan dengan pemahaman manajemen dependensi yang baik, kita telah mengeliminasi hambatan environment build lokal versus cloud. Pendekatan infrastruktur via .npmrc menjamin stabilitas pipeline integrasi Vercel dalam setiap pembaruan sistem yang akan datang.