Belajar Shiki Rehype Pretty Code - Performance & Troubleshooting

#Pendahuluan

Semua orang akan menemui masalah: kode tidak berwarna, bahasa tidak dikenali, atau build gagal karena WASM. Yang membedakan developer berpengalaman bukan kebebasan dari error, melainkan cara mendiagnosis dengan sistematis.

Episode 19 membahas strategi debugging dan troubleshooting: memeriksa output HTML, memanfaatkan log build, lalu menangani masalah yang paling sering muncul seperti grammar tidak termuat, error WASM, bahasa tidak dikenali, meta tidak ter-parse, inline code tidak di-highlight, dan konflik CSS theme.

#Diagnostik Dasar

#Memeriksa Output HTML

Langkah pertama diagnosis selalu melihat hasil render. Jalankan build, buka halaman, dan periksa elemen code block di DevTools. Perhatikan tiga hal: apakah elemen berisi span token, apakah atribut seperti data-line-numbers muncul, dan apakah warna sesuai theme.

Jika elemen <code> hanya berisi teks polos tanpa span, berarti rehype-pretty-code tidak pernah menjalankan highlight. Jika span ada tetapi warna salah, masalahnya berada di CSS atau theme.

#Menelusuri dengan Output Build

Untuk melihat hasil pipeline tanpa membuka browser, render satu dokumen kecil di Node.js dan cetak HTML-nya:

node diagnose.mjs

diagnose.mjs

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypePrettyCode from "rehype-pretty-code";
import rehypeStringify from "rehype-stringify";
 
const markdown = "```ts\nconst a = 1;\n```\n";
const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypePrettyCode, { theme: "github-dark-default" })
  .use(rehypeStringify)
  .process(markdown);
 
console.log(String(file));

Skrip kecil ini menampilkan HTML mentah dari satu blok kode. Bandingkan dengan harapan kalian: jika span tidak ada, masalah ada di pipeline atau konfigurasi plugin.

#Mengamati Log dan Peringatan

#Mengaktifkan Peringatan

Shiki menyembunyikan banyak peringatan secara default. Aktifkan log dengan opsi warnings: "warn" agar masalah seperti bahasa yang tidak dikenali muncul saat build:

Aktifkan peringatan

const options = {
  theme: "github-dark-default",
  warnings: "warn",
};

Dengan opsi warnings, proses build menampilkan peringatan ke terminal alih-alih diam-diam gagal. Terapkan ini di lingkungan pengembangan, lalu nonaktifkan saat produksi jika log sudah bersih.

#Membaca Log Build

Perhatikan urutan pesan build: pesan pertama yang menyebut "language" atau "wasm" biasanya menjadi petunjuk utama. Catat nama file dan baris yang gagal, lalu bandingkan dengan daftar bahasa yang didaftarkan pada opsi langs. Kesalahan kecil seperti typo id bahasa sering menjadi biang kerok.

#Troubleshooting Grammar dan WASM

#Bahasa Tidak Termuat

Error "No language registered for X" berarti grammar X tidak ada di daftar langs pada konfigurasi. Solusinya tambahkan id bahasa tersebut:

node -e "import('@shikijs/langs').then(m => console.log(m.langs.some(l => l.id === 'rust')))"

Jika perintah menampilkan false, id yang kalian tulis salah. Periksa daftar bahasa lengkap di package @shikijs/langs untuk menemukan id yang benar.

#Error WASM

Error seperti "Failed to fetch dynamically imported module" pada file shiki/wasm menandakan file WASM tidak ditemukan. Pastikan environment kalian mendukung import dinamis untuk aset WASM, dan pada Next.js periksa bahwa output: standalone tidak mengecualikan file WASM dari server build.

Jika memakai serverless, hindari memuat WASM di runtime; pindahkan highlight ke build-time dengan SSG. Engine JavaScript dari @shikijs/engine-javascript menjadi alternatif saat WASM benar-benar tidak tersedia.

#Troubleshooting Meta dan Inline Code

#Meta String Tidak Ter-Parse

Meta string yang tidak berpengaruh biasanya karena format salah. Perhatikan urutan dan kutipan: nilai dengan spasi harus dikelilingi tanda kutip, sedangkan fitur tanpa nilai seperti showLineNumbers ditulis polos. Jika atribut tidak muncul di markup, periksa kembali baris meta pada fenced code block dan bandingkan dengan contoh di episode 6.

#Inline Code Tidak Di-Highlight

Jika kode inline tetap polos, kemungkinan besar bypassInlineCode belum disetel false. Setelah disetel, pastikan token memakai bahasa yang dikenali. Token yang warnanya tidak berubah bisa jadi memakai bahasa yang tidak didukung atau defaultLang bernilai plaintext.

#Meta Bahasa Tidak Dikenali pada Inline Code

Penanda bahasa pada kode inline hanya berfungsi jika bahasa tersebut terdaftar. Jika penanda memakai id yang tidak dikenal, tambahkan id bahasa tersebut ke opsi langs seperti pada code block biasa. Konsistensi daftar bahasa antara blok dan inline menghilangkan setengah masalah ini.

#Konflik dengan CSS Theme

#Warna Tertimpa Stylesheet

Highlight benar secara semantik tetapi warna tampak salah, misalnya semua token putih atau hijau seragam. Ini biasanya konflik CSS: aturan global seperti pre span { color: ... } menimpa warna token. Periksa DevTools untuk melihat aturan mana yang menimpa color: var(--shiki-dark).

Perbaiki dengan menargetkan lebih spesifik atau memakai atribut sebagai pembeda:

[data-rehype-pretty-code-figure] code span {
  color: var(--shiki-dark);
}

Selektifitas yang lebih tinggi mengalahkan aturan global yang longgar. Pastikan juga keepBackground tidak membuat background ganda saat theme dan CSS sama-sama mengatur latar.

#Penutup

Inti yang harus dibawa pulang:

• Diagnosis dimulai dengan memeriksa output HTML dan struktur span.
• Skrip Node.js kecil bisa merender satu blok untuk isolasi masalah.
• Opsi warnings memunculkan peringatan yang tersembunyi.
• Bahasa yang tidak dikenal perlu didaftarkan di opsi langs.
• Error WASM biasanya diselesaikan dengan memindahkan highlight ke build-time.
• Konflik CSS theme diselesaikan dengan selektifitas selector yang lebih tinggi.

Di episode 20 kalian akan belajar fitur stabil terbaru Shiki 4 dan rehype-pretty-code 0.14: perombakan API highlighter, opsi engine, pemisahan langs dan themes menjadi package tersendiri, serta perbaikan inline character highlighting pada rehype-pretty-code.