Fase 0 · Fondasi: Node, TypeScript & Cara Pikir Astro

Node 22, pnpm & memasang Astro

Astro 7 menuntut Node 22.12 ke atas. Sebelum menulis satu baris komponen, ada empat keputusan toolchain yang kalau salah akan menghantui sampai tahap deploy.

Sumber asli docs.astro.build Resmi Rangkuman ~7 menit baca

Intisari

Astro 6 dan 7 butuh Node 22.12+. Node 20 sudah tidak didukung — ini bukan peringatan, tapi kegagalan build.
Versi Node dikunci per proyek lewat .nvmrc atau engines, bukan diinstal global seperti PHP.
pnpm-lock.yaml wajib di-commit. Ia setara composer.lock, dan tanpanya build produksimu tidak reprodusibel.
node_modules tidak pernah ikut ke image Docker — ia dibangun ulang di dalam build stage.
Perintah yang menentukan cuma tiga: dev, build, dan preview. preview yang paling sering dilewatkan orang, dan justru itu yang menyerupai produksi.

Empat menit pertama

node --version          # wajib v22.12.0 atau lebih baru
corepack enable pnpm    # pnpm ikut Node, tidak perlu diinstal terpisah

pnpm create astro@latest portal-berita
cd portal-berita
pnpm dev

pnpm create astro@latest akan bertanya beberapa hal. Untuk proyek portal berita yang akan kita bangun sepanjang roadmap ini, jawablah: template Empty, TypeScript Strict, dan install dependencies Yes. Template berisi contoh justru memperlambat — isinya harus kamu hapus semua sebelum bisa mulai.

Kenapa corepack, bukan npm i -g pnpm. Corepack sudah ikut di dalam Node dan mengunci versi pnpm ke field packageManager di package.json. Artinya laptopmu, laptop rekanmu, dan runner CI memakai pnpm versi yang sama persis — tanpa ada yang perlu mengingat untuk meng-update apa pun. Ini yang tidak bisa dilakukan composer global require.

Tiga kebiasaan Composer yang menyesatkan di sini

Kebiasaan dari PHP	Kenapa keliru di Node
Satu versi PHP untuk seluruh mesin	Tiap proyek Node punya versi Node sendiri. Pasang nvm atau Volta, lalu tulis `.nvmrc` berisi `22` dan commit.
`vendor/` kadang ikut di-commit	`node_modules` tidak pernah. Isinya bisa puluhan ribu file dan sebagian berisi binari khusus platform — yang dibangun di macOS tidak jalan di container Linux.
Dependensi runtime dan dev sama-sama terpasang di produksi	Astro mem-bundle apa yang dibutuhkan saat `build`. Yang berjalan di produksi adalah isi `dist/`, bukan `node_modules`-mu — kecuali dependensi yang sengaja di-externalize (Fase 10).

Isi `package.json` yang menentukan

{
  "name": "portal-berita",
  "type": "module",
  "packageManager": "[email protected]",
  "engines": { "node": ">=22.12.0" },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "check": "astro check"
  }
}

"type": "module" membuat seluruh berkas .js di proyek diperlakukan sebagai ESM — import, bukan require. Astro mengaturnya otomatis saat scaffolding, dan mengubahnya kembali ke CommonJS akan merusak sebagian besar dependensi modern. Biarkan.

engines tidak menghentikan siapa pun secara default, tapi pnpm akan menolak memasang kalau kamu tambahkan engine-strict=true di .npmrc. Di tim, lakukan itu — lebih baik gagal saat pnpm install daripada gagal misterius saat build di CI.

Tiga perintah, tiga dunia yang berbeda

Perintah	Yang terjadi	Kapan dipakai
`pnpm dev`	Server Vite dengan HMR. Kode tidak dibundel, modul disajikan satu per satu.	Saat menulis kode. Bukan tolok ukur performa apa pun.
`pnpm build`	Menghasilkan `dist/`. Halaman statis dirender jadi HTML sekarang juga; halaman on-demand dibundel jadi kode server.	Sebelum deploy, dan di CI pada tiap pull request.
`pnpm preview`	Menjalankan hasil `dist/` apa adanya, tanpa HMR dan tanpa source map dev.	Sebelum bilang "sudah selesai". Ini satu-satunya yang menyerupai produksi.

Bug yang cuma muncul di produksi hampir selalu ketahuan di preview. Penyebabnya berulang: kode yang mengakses window atau document saat render server, variabel lingkungan yang ada di .env lokal tapi tidak diteruskan ke container, dan import yang bekerja di dev karena Vite memaafkan resolusi jalur yang tidak persis. Ketiganya diam di pnpm dev dan meledak di pnpm build atau pnpm preview.

Struktur berkas hasil scaffolding

portal-berita/
├── astro.config.mjs      # konfigurasi: integrasi, adapter, output
├── package.json
├── pnpm-lock.yaml        # COMMIT INI
├── tsconfig.json
├── .nvmrc                # berisi: 22
├── public/               # disalin apa adanya, TIDAK diproses
└── src/
    ├── pages/            # satu berkas = satu rute
    ├── layouts/
    ├── components/
    └── assets/           # diproses & di-hash saat build

Perbedaan public/ dan src/assets/ adalah hal pertama yang membingungkan pendatang, dan dibahas tuntas di materi Struktur proyek. Ringkasnya: apa pun yang butuh di-optimasi atau di-hash taruh di src/assets/; yang harus punya URL tetap dan bisa ditebak — robots.txt, favicon.ico, berkas verifikasi domain — taruh di public/.

Menambah dependensi yang akan kita pakai

# Integrasi Vue untuk island interaktif (Fase 4)
pnpm astro add vue

# Adapter Node untuk rendering on-demand (Fase 1 & 10)
pnpm astro add node

# Database (Fase 2)
pnpm add kysely mysql2

astro add bukan sekadar pnpm add. Ia memasang paketnya dan menyunting astro.config.mjs untuk mendaftarkan integrasinya. Untuk paket yang bukan integrasi Astro — kysely, mysql2 — pakai pnpm add biasa.

Latihan: buat proyek portal-berita dengan template Empty dan TypeScript strict. Tulis .nvmrc berisi 22, tambahkan engine-strict=true di .npmrc, lalu buktikan pagarnya bekerja: ubah sementara engines.node jadi ">=99" dan jalankan pnpm install — ia harus menolak. Kembalikan, lalu jalankan pnpm build && pnpm preview dan buka hasilnya di browser. Catat berapa berkas yang ada di dist/.

Rangkuman ini sengaja dipangkas ke bagian yang dipakai di roadmap. Buka sumber aslinya saat kamu butuh detail lengkap atau referensi parameter.