Cara menggunakan dynamic import Node.js yang benar adalah memanggil await import() di dalam fungsi async dengan path lengkap beserta extension. Banyak yang gagal karena memanggilnya seperti require() di top-level sinkron atau lupa menulis .js di path. Hasilnya selalu Promise berisi namespace object modul.
Bentuk Dasar Dynamic Import di CommonJS dan ES Module
Fungsi import() bisa dipakai di file CommonJS maupun file type: module. Bedanya hanya cara fungsi pembungkusnya ditulis.
// app.cjs, tetap CommonJS tapi bisa lazy load
async function loadAdmin() {
if (process.env.ADMIN === "1") {
const mod = await import("./admin.js");
return mod.default || mod;
}
return null;
}
Setelah import selesai, cek bentuk exportnya:
- Gunakan
mod.defaultuntukexport defaultataumodule.exports =. - Gunakan
mod.namaFungsiuntuk named export sepertiexport function namaFungsi. - Gunakan
console.log(mod)sekali saat ragu dengan struktur modul target.
Langkah Memuat Modul Secara Lazy dan Kondisional
- Siapkan file target. Misal
heavy.mjsmemakaiexportdanlegacy.cjsmemakaimodule.exports. - Panggil dengan path relatif dan extension jelas:
await import("./heavy.mjs"). Node.js tidak menebak extension seperti bundler. - Bungkus dengan
try catchagarERR_MODULE_NOT_FOUNDtidak mematikan proses. - Simpan hasilnya di variabel cache kalau modul dipakai berulang. Jangan panggil
import()di dalam loop besar tanpa cache.
let cached;
async function getHeavy() {
if (!cached) cached = await import("./heavy.mjs");
return cached;
}
Tabel Pola Gagal Dynamic Import dan Perbaikannya
| Masalah | Penyebab | Solusi |
|---|---|---|
| ERR_MODULE_NOT_FOUND | Path tanpa extension | Tulis ./util.js lengkap |
| SyntaxError top-level await | Dipanggil di fungsi sync | Bungkus dengan async function |
| ERR_REQUIRE_ESM | require() ke file ESM |
Ganti ke await import() |
FAQ
Apakah dynamic import butuh type module?
Tidak. await import() jalan di CommonJS maupun ES Module, asal dipanggil dari konteks async.
Bagaimana cara import JSON atau CommonJS dengan import()?
Modul CommonJS terbaca sebagai default export, sedangkan JSON butuh import attributes sesuai versi Node.js yang dipakai.
Kenapa dynamic import tetap error ERR_MODULE_NOT_FOUND?
Path relatif salah atau extension hilang, cek process.cwd() dan nama file tujuan.