Load Modul Seperlunya dengan Cara Menggunakan Dynamic Import Node Js

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.default untuk export default atau module.exports =.
  • Gunakan mod.namaFungsi untuk named export seperti export function namaFungsi.
  • Gunakan console.log(mod) sekali saat ragu dengan struktur modul target.

Langkah Memuat Modul Secara Lazy dan Kondisional

  1. Siapkan file target. Misal heavy.mjs memakai export dan legacy.cjs memakai module.exports.
  2. Panggil dengan path relatif dan extension jelas: await import("./heavy.mjs"). Node.js tidak menebak extension seperti bundler.
  3. Bungkus dengan try catch agar ERR_MODULE_NOT_FOUND tidak mematikan proses.
  4. 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.