Cara Mengatasi Module Not Found di Next.js

Error “Module Not Found” adalah salah satu bug paling umum dan sering membuat frustrasi para developer JavaScript, termasuk di Next.js. Pesan error ini muncul ketika kompiler atau runtime Next.js tidak dapat menemukan modul atau file yang coba Anda import. Ini bisa terjadi karena berbagai alasan, mulai dari kesalahan ketik sederhana hingga masalah konfigurasi yang lebih kompleks.

Sebagai seorang developer yang sudah sering berkutat dengan Next.js, saya tahu betul betapa menjengkelkannya melihat error ini berulang kali. Tapi jangan khawatir, sebagian besar masalah “Module Not Found” memiliki solusi yang cukup straightforward. Artikel ini akan memandu Anda melalui penyebab paling umum dan langkah-langkah praktis untuk mengatasinya, agar Anda bisa kembali fokus membangun aplikasi Next.js Anda.

Penyebab Umum “Module Not Found” di Next.js dan Solusinya

Mari kita selami berbagai skenario yang dapat memicu error “Module Not Found” dan bagaimana cara memperbaikinya.

1. Salah Penulisan Path atau Nama Modul

Ini adalah penyebab paling dasar dan seringkali terlewat. Kesalahan ketik pada nama file, nama folder, atau path import adalah biang keladinya.

• Gejala: Error menunjuk langsung ke baris import dan path yang Anda tulis.
• Penyebab:
  • Kesalahan ketik pada nama modul (misal: './component/Button' padahal seharusnya './components/Button').
  • Kesalahan ketik pada nama variabel import (misal: import { Button } padahal seharusnya import { MyButton }).
  • Path relatif yang tidak akurat (misal: '../utils/helpers' padahal seharusnya '../../utils/helpers').
• Solusi:
  • Periksa kembali setiap huruf pada path dan nama modul yang Anda import. Pastikan semuanya sesuai dengan nama file/folder yang sebenarnya.
  • Manfaatkan fitur auto-completion dari IDE Anda (seperti VS Code) untuk meminimalkan kesalahan ketik.

2. Modul Eksternal Belum Terinstall atau Hilang

Ketika Anda mengimport sebuah pustaka dari npm (misalnya lodash, react-query, atau pustaka UI seperti shadcn/ui), Next.js perlu memastikan pustaka tersebut ada di folder node_modules proyek Anda.

• Gejala: Error “Module Not Found” yang menyebut nama paket npm (misal: "Module not found: Can't resolve 'axios'").
• Penyebab:
  • Anda lupa menginstall paket tersebut (misal: axios belum diinstall).
  • node_modules Anda rusak atau tidak lengkap (misalnya setelah git pull dari rekan tim).
  • Paket tersebut ada di package.json tetapi belum diinstall (setelah kloning repo baru).
• Solusi:
  • Install paket yang hilang menggunakan package manager Anda:
    • npm install nama-paket
    • yarn add nama-paket
    • pnpm add nama-paket
  • Jika Anda baru saja mengkloning repositori atau node_modules Anda terasa “berantakan”, hapus folder node_modules dan file package-lock.json (atau yarn.lock/pnpm-lock.yaml), lalu install ulang semua dependensi:

    rm -rf node_modules package-lock.json
    npm install

3. Import Path yang Salah (Relatif vs. Absolut vs. Alias)

Next.js mendukung beberapa jenis import path. Menggunakan jenis yang salah atau tidak konsisten dapat menyebabkan kebingungan.

• Gejala: Error menunjukkan path yang terlihat benar tapi tidak ditemukan, atau path relatif yang sangat panjang (misal: '../../../components/Button').
• Penyebab:
  • Menggunakan path relatif yang tidak akurat.
  • Mencoba menggunakan absolute import (misal: '@/components/Button') tanpa mengkonfigurasi alias path di jsconfig.json (untuk JavaScript) atau tsconfig.json (untuk TypeScript).
• Solusi:
  • Untuk path relatif: Pastikan Anda menghitung jumlah ../ dengan benar untuk keluar dari folder dan masuk ke folder yang dituju.
  • Untuk absolute import (direkomendasikan): Konfigurasi alias path di jsconfig.json atau tsconfig.json. Ini sangat membantu untuk proyek besar.

    Contoh jsconfig.json:

    {
      "compilerOptions": {
        "baseUrl": ".",
        "paths": {
          "@/*": ["./*"]
        }
      },
      "include": ["next-env.d.ts", "/*.ts", "/*.tsx", "/*.js", "/*.jsx"],
      "exclude": ["node_modules"]
    }

    Dengan konfigurasi ini, Anda bisa mengimport seperti import Button from '@/components/Button'; dari mana saja di proyek Anda.

4. Case Sensitivity File System

Ini adalah jebakan umum, terutama bagi developer yang beralih antara sistem operasi (misalnya dari Windows ke Linux/macOS atau sebaliknya). Windows secara default tidak peka huruf besar/kecil (case-insensitive), sementara Linux dan macOS peka huruf besar/kecil (case-sensitive).

• Gejala: Kode berfungsi di satu OS tetapi tidak di OS lain. Error menunjukkan path yang terlihat identik.
• Penyebab:
  • Anda memiliki file bernama mycomponent.js tetapi mengimportnya sebagai './MyComponent'.
  • Anda memiliki folder bernama components tetapi mengimport dari './Components/Button'.
• Solusi:
  • Pastikan nama file dan folder Anda di disk (file system) sama persis dengan yang Anda tulis dalam statement import, termasuk penggunaan huruf besar/kecil.
  • Biasakan menggunakan konvensi penamaan yang konsisten (misal: PascalCase untuk komponen, kebab-case untuk file CSS/utility).

5. Konfigurasi Transpilasi Bermasalah

Next.js menggunakan Babel dan Webpack di belakang layar untuk mentranspilasi kode Anda. Terkadang, konfigurasi yang salah dapat menyebabkan modul tidak dikenali.

• Gejala: Error terjadi pada modul yang tampaknya terinstall dengan benar, seringkali melibatkan sintaks ES Modules (import/export) atau CommonJS (require/module.exports). Ini juga sering muncul ketika mengimport komponen UI yang belum di-transpile oleh Next.js.
• Penyebab:
  • Anda mengimport modul CommonJS di lingkungan ES Modules atau sebaliknya tanpa konfigurasi yang tepat.
  • Anda menggunakan pustaka pihak ketiga yang belum di-transpile ke sintaks yang bisa dipahami Next.js secara default (misalnya, di monorepo).
  • Konfigurasi next.config.js yang salah untuk Webpack atau Babel.
• Solusi:
  • Untuk pustaka pihak ketiga yang perlu ditranspilasi: Di Next.js 13 ke atas, gunakan opsi transpilePackages di next.config.js. Ini sangat berguna untuk monorepo atau saat menggunakan pustaka yang tidak teroptimasi untuk ES Modules di browser.

    // next.config.js
    / @type {import('next').NextConfig} */
    const nextConfig = {
      transpilePackages: ['nama-paket-yang-perlu-ditranspilasi'], // Contoh: ['@mui/x-charts']
    };
    
    module.exports = nextConfig;

  • Pastikan tidak ada konfigurasi Babel atau Webpack kustom yang bertentangan dengan Next.js default, kecuali jika Anda tahu persis apa yang Anda lakukan.

6. Konflik Antara Server-side dan Client-side Import

Next.js mendukung rendering sisi server (SSR) dan client-side rendering (CSR). Modul yang dirancang hanya untuk lingkungan browser (misalnya, yang mengakses window atau document) akan gagal saat diimport dan dijalankan di sisi server.

• Gejala: Error “Module Not Found” diikuti dengan pesan seperti “ReferenceError: window is not defined” atau “document is not defined”.
• Penyebab: Anda mencoba mengimport modul yang hanya berjalan di browser (client-side) di dalam komponen yang di-render di server.
• Solusi: Gunakan Dynamic Import with ssr: false. Ini akan memastikan modul hanya dimuat di sisi client.

  import dynamic from 'next/dynamic';
  
  const ClientOnlyComponent = dynamic(() => import('../components/ClientOnly'), {
    ssr: false, // Penting! Jangan render di server
    loading: () => 
  Loading...
  , // Opsional: placeholder saat loading
  });
  
  export default function MyPage() {
    return (
      <div>
        <h1>Halaman Ini Memiliki Komponen Client-Only</h1>
        <ClientOnlyComponent />
      </div>
    );
  }

7. Caching Bermasalah

Sistem cache yang terlalu agresif dari package manager atau bahkan cache build Next.js itu sendiri dapat menyebabkan masalah di mana perubahan pada file atau instalasi modul tidak terdeteksi.

• Gejala: Anda sudah yakin semua path dan instalasi benar, tetapi error tetap muncul.
• Penyebab:
  • Cache npm/yarn/pnpm yang menyimpan versi paket lama.
  • Cache build Next.js di folder .next/.
• Solusi:
  • Hapus folder .next/ di root proyek Anda.
  • Hapus folder node_modules/ dan file package-lock.json (atau yarn.lock/pnpm-lock.yaml).
  • Jalankan perintah untuk membersihkan cache package manager (jika perlu):
    • npm cache clean --force
    • yarn cache clean
    • pnpm store prune
  • Install ulang semua dependensi: npm install atau yarn atau pnpm install.
  • Restart development server Next.js Anda (npm run dev).

8. Isu di Monorepo atau Proyek Multi-paket

Jika Anda bekerja di lingkungan monorepo (misalnya dengan Turborepo, Lerna, atau NX), mengelola dependensi antar paket bisa menjadi lebih rumit.

• Gejala: Modul yang berada di dalam salah satu paket lokal (misal: 'ui-kit') tidak ditemukan oleh aplikasi Next.js Anda.
• Penyebab:
  • Dependensi tidak di-hoist dengan benar oleh package manager.
  • Next.js tidak mengerti cara mentranspilasi kode dari paket lokal.
  • Symlink yang rusak antar paket.
• Solusi:
  • Pastikan semua paket lokal terdaftar sebagai dependensi di package.json aplikasi Next.js Anda (biasanya di bagian dependencies atau devDependencies).
  • Gunakan transpilePackages di next.config.js Next.js Anda untuk semua paket lokal yang perlu ditranspilasi (seperti dijelaskan di poin 5).
  • Periksa konfigurasi monorepo Anda (package.json, lerna.json, turbo.json) untuk memastikan hoisting dependensi dan workspace dikelola dengan benar.
  • Coba lakukan npm install (atau yarn / pnpm install) di root monorepo, bukan hanya di sub-proyek.

9. Versi Next.js atau Dependensi yang Usang/Tidak Kompatibel

Terkadang, masalah “Module Not Found” bisa muncul karena ketidakcocokan versi antara Next.js dan salah satu dependensi Anda, terutama setelah Next.js melakukan major update.

• Gejala: Error muncul setelah memperbarui Next.js atau dependensi lain, atau ketika Anda menggunakan fitur/modul yang baru.
• Penyebab:
  • Modul yang Anda gunakan belum kompatibel dengan versi Next.js terbaru.
  • Versi Next.js yang Anda gunakan terlalu lama untuk modul tertentu.
• Solusi:
  • Perbarui semua dependensi Anda ke versi terbaru: npm update atau yarn upgrade.
  • Periksa dokumentasi resmi Next.js dan modul yang bermasalah untuk mengetahui persyaratan versi atau breaking changes.
  • Jika ada modul yang benar-benar tidak kompatibel, Anda mungkin perlu mencari alternatif atau downgrade Next.js (meskipun ini jarang direkomendasikan).

Masalah yang Sering Terjadi

Berikut adalah beberapa skenario spesifik “Module Not Found” yang sering saya temui dan solusinya:

Module not found: Can’t resolve ‘fs’ atau ‘path’

Ini adalah error klasik ketika Anda mencoba mengimport modul Node.js built-in seperti fs (File System) atau path di komponen yang akan di-render di sisi klien. Modul ini hanya tersedia di lingkungan Node.js (server-side).

• Solusi:
  1. Jika Anda benar-benar membutuhkan fungsionalitas ini, pastikan code tersebut hanya dijalankan di server. Gunakan if (typeof window === 'undefined') untuk kondisi server-only.
  2. Gunakan Dynamic Import dengan ssr: false untuk komponen yang mengimport modul tersebut (seperti dijelaskan di poin 6).
  3. Refaktor kode agar operasi file system dilakukan di API routes atau getServerSideProps/getStaticProps.

Module not found: Can’t resolve ‘./my-component.css’ atau ‘./styles.module.css’

Error ini terjadi saat mengimport file CSS atau CSS Module.next.js memiliki cara spesifik untuk menangani CSS.

• Solusi:
  1. Pastikan file CSS/CSS Module Anda memiliki ekstensi yang benar (.css atau .module.css).
  2. Pastikan Anda mengimport CSS global di _app.js (atau _app.tsx) atau mengimport CSS Module secara lokal ke komponen yang sesuai.
  3. Next.js secara otomatis mendukung CSS Modules. Untuk CSS biasa, Anda mungkin perlu menginstall @zeit/next-css (untuk Next.js versi lama) atau pastikan konfigurasi Webpack Anda benar jika Anda melakukan konfigurasi kustom. Untuk Next.js versi baru, support CSS sudah built-in.

Module not found: Can’t resolve ‘my-npm-package’ padahal sudah install

Anda sudah yakin paketnya ada di package.json dan sudah menjalankan npm install, tapi error masih muncul.

• Solusi:
  1. Periksa kembali ejaan nama paket di statement import dan di package.json.
  2. Coba hapus node_modules dan package-lock.json, lalu install ulang seperti dijelaskan di poin 2 (Solusi “Modul Eksternal Belum Terinstall atau Hilang”).
  3. Kadang ada masalah dengan cache Webpack Next.js. Coba hapus folder .next/ dan restart development server Anda.
  4. Verifikasi apakah paket tersebut benar-benar di-hoist dengan benar, terutama di setup monorepo.

Pengalaman dan Pertimbangan Praktis

Sebagai seorang developer, saya telah menghadapi “Module Not Found” dalam berbagai skenario. Berikut adalah beberapa pengalaman dan pertimbangan praktis yang mungkin berguna:

• Gunakan IDE yang Kuat: Visual Studio Code dengan ekstensi seperti ESLint dan Prettier sangat membantu. Fitur auto-completion dan error highlighting-nya seringkali bisa mendeteksi kesalahan path bahkan sebelum Anda menjalankan kode. Saya pribadi mengandalkan fitur ini setiap hari.
• Pentingnya Konsistensi: Di proyek yang lebih besar, konsistensi dalam penamaan file, struktur folder, dan cara import (misalnya, selalu gunakan absolute import) adalah kunci. Ini mengurangi kemungkinan kesalahan dan membuat codebase lebih mudah dikelola.
• Debugging yang Sistematis: Jangan panik saat melihat error. Mulailah dari penyebab paling sederhana (kesalahan ketik, modul belum terinstall) sebelum beralih ke konfigurasi yang lebih kompleks. Seringkali, masalahnya jauh lebih sederhana dari yang kita duga. Saya punya kebiasaan mencoba restart dev server dan menginstall ulang dependensi sebagai langkah pertama yang cepat.
• Alias Path adalah Penyelamat: Saya sangat merekomendasikan penggunaan alias path di jsconfig.json atau tsconfig.json. Ini secara drastis mengurangi panjang import path relatif (../../../) dan membuat kode lebih mudah dibaca dan di-refactor.
• Monitor Versi Dependensi: Di ekosistem JavaScript yang bergerak cepat, versi dependensi bisa menjadi masalah. Saya sering memeriksa changelog atau isu di GitHub ketika saya memperbarui Next.js atau pustaka utama dan tiba-tiba menghadapi masalah. Ada alat seperti Dependabot atau Renovate yang bisa membantu otomatisasi ini.
• Monorepo Membutuhkan Perhatian Ekstra: Jika Anda menggunakan monorepo, bersiaplah untuk menghadapi tantangan ekstra terkait Module Not Found. transpilePackages di Next.js 13+ adalah fitur krusial yang harus Anda pahami. Juga, pastikan Anda paham bagaimana package manager Anda (npm, Yarn, pnpm) mengelola workspaces dan hoisting.

FAQ

Apa itu error “Module Not Found”?

“Module Not Found” adalah pesan error yang muncul ketika program (dalam hal ini, aplikasi Next.js Anda) tidak dapat menemukan file atau pustaka yang Anda coba gunakan melalui statement import atau require. Ini berarti lokasi file atau nama modul yang Anda sebutkan tidak dapat ditemukan di jalur yang diharapkan.

Mengapa Next.js sensitif terhadap case sensitivity?

Next.js di lingkungan produksi (dan seringkali di pengembangan) menggunakan sistem file yang peka huruf besar/kecil (seperti Linux atau macOS), meskipun Anda mungkin mengembangkan di Windows yang tidak peka huruf besar/kecil secara default. Ini berarti MyComponent.js dan mycomponent.js dianggap sebagai dua file yang berbeda. Jika Anda mengimport MyComponent tetapi nama file aslinya mycomponent.js, maka di lingkungan produksi akan terjadi error “Module Not Found”.

Bagaimana cara menggunakan absolute import di Next.js?

Anda dapat mengkonfigurasi absolute import di Next.js dengan menambahkan file jsconfig.json (untuk JavaScript) atau tsconfig.json (untuk TypeScript) di root proyek Anda. Di dalamnya, tambahkan konfigurasi baseUrl dan paths. Contohnya, "@/*": ["./*"] akan memungkinkan Anda mengimport file dari root proyek menggunakan @/ sebagai alias.

Apa fungsi transpilePackages di Next.js?

transpilePackages adalah opsi konfigurasi di next.config.js (tersedia di Next.js 13 ke atas) yang memungkinkan Anda memberitahu Next.js untuk secara eksplisit mentranspilasi (mengubah dari satu sintaks ke sintaks lain, misalnya dari ESNext ke ES5) paket npm tertentu. Ini sangat berguna ketika Anda menggunakan pustaka pihak ketiga atau paket lokal di monorepo yang mungkin menggunakan sintaks JavaScript modern dan perlu diolah oleh Babel/Webpack Next.js agar kompatibel dengan browser target.

Haruskah saya menghapus node_modules setiap kali ada error?

Tidak selalu. Menghapus node_modules dan package-lock.json (atau file lock lainnya) lalu menginstall ulang adalah “solusi nuklir” yang sering berhasil mengatasi masalah dependensi yang aneh atau cache yang rusak. Namun, ini memakan waktu. Coba langkah-langkah debugging yang lebih sederhana terlebih dahulu, seperti memeriksa path, nama file, atau menjalankan npm install biasa. Lakukan langkah “hapus dan install ulang” hanya jika cara lain tidak berhasil.

Kesimpulan

Error “Module Not Found” di Next.js memang menjengkelkan, tetapi jarang sekali tidak memiliki solusi. Kunci untuk mengatasinya adalah dengan pendekatan yang sistematis: mulai dari memeriksa hal-hal dasar seperti kesalahan ketik dan instalasi modul, hingga menyelami konfigurasi yang lebih dalam seperti alias path, transpilasi, atau masalah server/client-side rendering.

Dengan memahami penyebab umum dan solusi yang telah dibahas di atas, Anda akan jauh lebih siap menghadapi error ini. Jangan lupa untuk selalu mengandalkan IDE Anda, menjaga konsistensi kode, dan yang terpenting, jangan ragu untuk membersihkan cache dan menginstall ulang dependensi jika Anda merasa ada yang tidak beres. Kode yang bersih, konfigurasi yang rapi, dan pemahaman yang baik tentang Next.js akan meminimalkan waktu yang Anda habiskan untuk debugging dan memaksimalkan waktu Anda untuk membangun fitur-fitur keren!

TAGS: Next.js, Module Not Found, JavaScript, Troubleshooting, Web Development, Programming Errors, Developer Tools, Frontend, npm

Baca Juga

• Panduan Lengkap Belajar Coding untuk Pemula hingga Profesional

Related posts:

Cara Membuat REST API Sederhana Menggunakan Express.js: Panduan Lengkap untuk Developer Pemula Cara Menjalankan Flutter di Android Studio: Panduan Lengkap untuk Developer Mengirim Request POST di PHP: Panduan Lengkap untuk Developer Modern (cURL, Guzzle, file_get_contents) Panduan Lengkap: Cara Menghubungkan PHP ke MySQL dengan MySQLi & PDO (Anti SQL Injection)