Jika kamu sedang membangun proyek web modern dengan Tailwind CSS dan tiba-tiba proses build gagal dengan pesan error yang menyebutkan @tailwindcss/postcss, kamu tidak sendirian. Error ini termasuk salah satu yang paling sering muncul, terutama saat migrasi dari Tailwind CSS v3 ke v4 atau saat pertama kali menyiapkan proyek baru. Artikel ini akan membongkar secara menyeluruh apa yang sebenarnya terjadi, mengapa error ini muncul, dan bagaimana cara memperbaikinya secara permanen agar kamu tidak perlu lagi mengulangi perbaikan yang sama setiap kali memulai proyek baru.

Anatomi Pesan Error

Ketika error ini muncul, biasanya kamu akan melihat pesan yang kurang lebih seperti berikut di terminal:

Error: Cannot find module '@tailwindcss/postcss'
Require stack:
- /path/to/project/postcss.config.js
- /path/to/project/node_modules/postcss-load-config/src/index.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1077:15)
    at Function.Module._load (node:internal/modules/cjs/loader:922:27)
    at Module.require (node:internal/modules/cjs/loader:1143:19)
    at require (node:internal/modules/cjs/helpers:119:18)
    at Object.<anonymous> (/path/to/project/postcss.config.js:2:24)
    at Module._compile (node:internal/modules/cjs/loader:1256:14)
    ...

Sederhananya, pesan ini berarti: Node.js tidak dapat menemukan paket bernama @tailwindcss/postcss yang sudah kamu rujuk di file konfigurasi PostCSS. Sistem mencoba memuat modul tersebut karena file postcss.config.js merujuk ke dalamnya, tetapi modul tersebut tidak ada di dalam direktori node_modules atau tidak dapat di-resolve oleh Node.js.

Kenapa bisa muncul? Intinya, ada diskoneksi antara apa yang ditulis di file konfigurasi dan apa yang benar-benar terinstal di proyek. PostCSS menjalankan file konfigurasi, menemukan referensi ke @tailwindcss/postcss, lalu meminta Node.js untuk me-resolve modul tersebut. Ketika Node.js gagal menemukannya, ia melempar error Cannot find module. Stack trace yang mengikuti pesan error menunjukkan rantai pemanggilan fungsi, dimulai dari file postcss.config.js milikmu, kemudian ke postcss-load-config yang bertugas membaca konfigurasi, hingga akhirnya ke internal loader Node.js yang gagal menemukan file yang diminta.

Penting untuk dipahami bahwa @tailwindcss/postcss adalah paket yang diperkenalkan sebagai bagian dari arsitektur baru Tailwind CSS v4. Di Tailwind CSS v3, plugin PostCSS untuk Tailwind biasanya direferensikan sebagai tailwindcss langsung di konfigurasi PostCSS:

//(postcss.config.js untuk Tailwind v3 — masih valid untuk v3)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Namun di Tailwind CSS v4, arsitekturnya berubah. Paket @tailwindcss/postcss menjadi plugin PostCSS resmi yang terpisah dari paket utama tailwindcss. Jadi, jika kamu mengikuti dokumentasi v4 tetapi lupa menginstal paketnya, atau justru mengikuti tutorial v3 sambil menggunakan dependensi v4, error inilah yang akan menyambutmu.

// postcss.config.js untuk Tailwind v4
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Pemahaman tentang perbedaan arsitektur ini sangat krusial karena menentukan strategi perbaikan yang tepat. Bukan sekadar soal "instal paket yang hilang", tetapi juga soal memastikan seluruh ekosistem konfigurasi kamu konsisten dengan versi Tailwind yang digunakan.

Penyebab Umum

Ada beberapa akar masalah yang bisa memicu munculnya error ini. Berikut adalah lima penyebab paling umum, diurutkan dari yang paling sering ditemui di lapangan:

  • Paket @tailwindcss/postcss belum diinstal. Ini adalah penyebab paling jelas dan paling sering. Kamu menulis konfigurasi PostCSS yang merujuk ke @tailwindcss/postcss, tetapi lupa menjalankan perintah instalasi. Atau, kamu meng-clone repositori orang lain tanpa menjalankan instalasi dependensi terlebih dahulu. Tanpa paket ini di node_modules, Node.js tidak punya cara untuk memuatnya.

  • Mencampur konfigurasi Tailwind v3 dengan dependensi v4 (atau sebaliknya). Misalnya, kamu menggunakan Tailwind v4 tetapi file postcss.config.js masih menggunakan format plugin tailwindcss: {} yang merupakan gaya v3, atau sebaliknya, kamu pakai v3 tetapi konfigurasi sudah merujuk ke @tailwindcss/postcss yang hanya ada di v4. Ketidakcocokan versi ini menyebabkan modul yang dirujuk tidak tersedia dalam paket yang terinstal.

  • File postcss.config.js merujuk ke nama modul yang salah. Kesalahan penulisan (typo) seperti @tailwindcss/PostCSS (huruf kapital) atau @tailwindcss/post-css (tanda hubung tambahan) akan menyebabkan Node.js gagal menemukan modul. Dalam dunia npm, nama paket bersifat case-sensitive dan setiap karakter penting.

  • node_modules tidak sinkron atau korup. Terkadang, paket sebenarnya sudah terinstal, tetapi karena proses instalasi yang terputus, cache npm yang bermasalah, atau konflik dengan package manager lain (misalnya menggunakan npm dan yarn secara bergantian), struktur node_modules menjadi tidak konsisten. File mungkin ada sebagian, atau symlink rusak, sehingga Node.js gagal me-resolve modul meskipun secara teori sudah diinstal.

  • Monorepo atau workspace dengan masalah hoisting. Dalam setup monorepo menggunakan tools seperti Turborepo, Nx, atau npm/yarn workspaces, paket mungkin terinstal di node_modules root workspace, tetapi PostCSS di sub-proyek mencari modul di node_modules lokal. Jika package manager tidak melakukan hoisting dengan benar, sub-proyek tidak akan bisa menemukan @tailwindcss/postcss.

Menemukan penyebab yang benar dimulai dari langkah diagnóstico yang sederhana. Pertama, periksa apakah paket benar-benar ada di node_modules dengan menjalankan ls node_modules/@tailwindcss/postcss di terminal. Jika direktori tersebut tidak ada, berarti paket memang belum terinstal atau instalasi gagal. Kedua, periksa versi Tailwind yang terinstal dengan npm list tailwindcss. Jika versi yang muncul adalah v3.x.x, maka kamu tidak seharusnya menggunakan @tailwindcss/postcss di konfigurasi PostCSS. Ketiga, periksa isi file postcss.config.js dan pastikan nama plugin yang ditulis sama persis dengan nama paket di package.json. Keempat, jika semuanya tampak benar, coba hapus node_modules dan instal ulang依赖—ini bisa mengungkap masalah korupsi atau sinkronisasi.

Cara Memperbaiki

Bagian ini akan membahas langkah-langkah perbaikan secara terperinci, langkah demi langkah, dengan perintah konkret dan Yang akan kamu lihat.

Langkah 1: Instal paket yang hilang

Jika paket @tailwindcss/postcss memang belum terinstal, jalankan perintah berikut sesuai package manager yang kamu gunakan:

# Menggunakan npm
npm install -D @tailwindcss/postcss

# Menggunakan yarn
yarn add -D @tailwindcss/postcss

# Menggunakan pnpm
pnpm add -D @tailwindcss/postcss

Yang akan kamu lihat setelah menjalankan perintah tersebut kira-kira seperti ini:

added 12 packages in 3s

Perintah ini akan menambahkan @tailwindcss/postcss ke dalam devDependencies di file package.json dan mengunduh paket beserta dependensinya ke node_modules. Flag -D (atau --save-dev) digunakan karena plugin PostCSS hanya dibutuhkan saat pengembangan dan build, bukan saat runtime di production.

Langkah 2: Pastikan konfigurasi PostCSS sudah benar

Setelah paket terinstal, verifikasi bahwa file postcss.config.js kamu menggunakan referensi yang tepat untuk versi Tailwind yang diinstal. Untuk Tailwind CSS v4, konfigurasi yang benar adalah:

// postcss.config.js (Tailwind CSS v4)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Sedangkan jika kamu masih menggunakan Tailwind CSS v3, konfigurasi yang tepat adalah:

// postcss.config.js (Tailwind CSS v3)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Jangan mencampur keduanya. Jika kamu menggunakan v3, jangan tulis @tailwindcss/postcss di konfigurasi, karena paket tersebut bukan bagian dari arsitektur v3 dan akan memicu error yang sama.

Langkah 3: Bersihkan dan instal ulang jika diperlukan

Jika paket sudah terinstal tapi error masih muncul, kemungkinan node_modules korup atau tidak sinkron. Jalankan langkah pembersihan berikut:

# Hapus node_modules dan lock file
rm -rf node_modules package-lock.json

# Instal ulang semua dependensi
npm install

Untuk pengguna pnpm, prosesnya serupa:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Yang akan kamu lihat adalah proses instalasi berjalan tanpa error dan diakhiri dengan pesan seperti added 247 packages in 8s. Setelah itu, jalankan kembali proses build untuk melihat apakah error sudah hilang.

Langkah 4: Perbaiki masalah hoisting di monorepo

Jika kamu bekerja dalam monorepo dan sub-proyek tidak bisa menemukan modul, tambahkan konfigurasi hoisting di file konfigurasi workspace. Untuk pnpm, buat atau edit file .npmrc di root workspace:

# .npmrc
shamefully-hoist=true
public-hoist-pattern[]=*@tailwindcss*

Untuk yarn workspaces, pastikan @tailwindcss/postcss dideklarasikan di dependencies atau devDependencies root package.json, bukan hanya di sub-proyek.

Verifikasi solusi berhasil

Setelah melakukan perbaikan, jalankan perintah build untuk memverifikasi:

npm run build

Atau jika menggunakan Vite:

npx vite build

Jika berhasil, kamu akan melihat output build yang selesai tanpa error, misalnya:

vite v5.4.0 building for production...
✓ 42 modules transformed.
dist/index.html                   0.42 kB │ gzip: 0.28 kB
dist/assets/index-DiwrgTda.css    6.78 kB │ gzip: 2.14 kB
dist/assets/index-CdR8bF6Y.js   142.31 kB │ gzip: 45.62 kB
✓ built in 1.23s

Selain itu, kamu juga bisa memverifikasi secara langsung bahwa modul bisa di-resolve oleh Node.js dengan skrip kecil:

node -e "require.resolve('@tailwindcss/postcss')"

Jika modul ditemukan, perintah ini akan mengembalikan path absolut ke file utama paket, misalnya /path/to/project/node_modules/@tailwindcss/postcss/index.js. Jika tidak ditemukan, Node.js akan melempar error Cannot find module.

Solusi di atas bersifat langsung karena menyerang akar masalah: paket yang hilang diinstal, konfigurasi yang salah diperbaiki, dan struktur node_modules yang korup dibersihkan. Ini bukan workaround, melainkan perbaikan yang menyelesaikan root cause secara langsung.

Fix Permanen (Bukan Workaround)

Memperbaiki error satu kali tidak cukup jika penyebab mendasarnya tidak ditangani. Di bagian ini, kita akan membahas konfigurasi dan Kebiasaan yang baik yang mencegah error ini muncul kembali, baik di proyek saat ini maupun di proyek-proyek mendatang.

Konsistensi versi di seluruh proyek

Masalah terbesar yang menyebabkan error ini berulang adalah inkonsistensi versi. Pastikan kamu secara eksplisit mendeklarasikan versi Tailwind CSS yang kompatibel di package.json. Hindari menggunakan rentang versi yang terlalu longgar seperti "tailwindcss": "^3.0.0" jika kamu benar-benar ingin menggunakan v3, karena ini bisa menyebabkan npm menginstal v4 ketika sudah dirilis sebagai latest stable.

{
  "devDependencies": {
    "tailwindcss": "4.x",
    "@tailwindcss/postcss": "4.x"
  }
}

Perhatikan bahwa kedua paket menggunakan versi mayor yang sama (4.x). Ini memastikan bahwa setiap kali kamu menjalankan npm install, versi yang kompatibel selalu terinstal. Jika kamu ingin lebih ketat lagi, sematkan versi eksplisit:

{
  "devDependencies": {
    "tailwindcss": "4.0.0",
    "@tailwindcss/postcss": "4.0.0"
  }
}

Template dan scaffold proyek

Cara terbaik mencegah error berulang adalah dengan membuat template proyek yang sudah benar dikonfigurasi. Buatlah repository template yang berisi file-file berikut:

// postcss.config.js — sudah siap untuk Tailwind v4
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
/* src/app.css — entry point CSS untuk Tailwind v4 */
@import "tailwindcss";
{
  "name": "my-tailwind-v4-template",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "4.x",
    "tailwindcss": "4.x",
    "vite": "^5.4.0"
  }
}

Dengan template ini, setiap kali memulai proyek baru, kamu cukup meng-clone template dan menjalankan npm install. Tidak ada lagi tebakan tentang konfigurasi mana yang benar karena semuanya sudah diatur sejak awal.

Konfigurasi PostCSS yang aman dengan fallback

Untuk proyek yang mungkin digunakan oleh banyak developer dengan environment berbeda, kamu bisa menambahkan pengecekan di postcss.config.js agar lebih graceful ketika modul tidak ditemukan:

// postcss.config.js dengan pengecekan
const tailwindcssPostcss = (() => {
  try {
    return require('@tailwindcss/postcss')
  } catch {
    console.warn(
      '[WARNING] @tailwindcss/postcss not found. ' +
      'Run: npm install -D @tailwindcss/postcss'
    )
    return require('postcss').plugin('noop', () => (tree) => tree)
  }
})()

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Pendekatan ini tidak menggantikan kebutuhan instalasi, tetapi memberikan pesan yang jelas dan tidak langsung crash, sehingga developer lain yang meng-clone proyek bisa langsung tahu apa yang harus dilakukan.

Perbedaan antar sistem operasi

Ada beberapa nuansa lintas OS yang perlu diperhatikan. Di Windows, masalah path yang mengandung spasi atau karakter khusus bisa menyebabkan Node.js gagal me-resolve modul. Pastikan proyek berada di path tanpa spasi, misalnya C:\Projects\my-app bukan C:\My Projects\my app. Selain itu, di Windows, perintah rm -rf tidak tersedia secara native di Command Prompt. Gunakan alternatif berikut:

# PowerShell di Windows
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install

Di macOS dan Linux, perintah rm -rf berjalan normal, tetapi bisa terjadi masalah permission jika node_modules atau file .cache dimiliki oleh root karena pernah menjalankan sudo npm install. Dalam kasus ini, kendalikan ownership:

# Perbaiki ownership di macOS/Linux
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) node_modules

Di semua OS, pastikan versi Node.js yang digunakan kompatibel. Tailwind CSS v4 membutuhkan Node.js versi 18 atau lebih baru. Periksa dengan:

node --version

Jika versimu di bawah 18, upgrade menggunakan nvm (Node Version Manager):

nvm install 20
nvm use 20

Kebiasaan yang baik terakhir yang sering diabaikan: commit file package-lock.json (atau yarn.lock, pnpm-lock.yaml) ke repository. Lock file memastikan bahwa setiap developer dan setiap environment mendapatkan versi paket yang persis sama, mengeliminasi kemungkinan inkonsistensi yang bisa memicu error Cannot find module.

Kalau Masih Belum Teratasi

Apabila masalahnya belum teratasi juga tetapi error masih tetap muncul, ada beberapa langkah lanjutan yang bisa dilakukan untuk mengungkap masalah yang lebih dalam.

Periksa konflik package manager

Salah satu penyebab tersembunyi yang sering terlewat adalah penggunaan lebih dari satu package manager dalam satu proyek. Misalnya, proyek mulanya menggunakan npm, lalu suatu saat kamu (atau anggota tim) menjalankan yarn install. Ini menciptakan dua lock file (package-lock.json dan yarn.lock) dan bisa menghasilkan struktur node_modules yang berbeda dan saling konflik. Solusinya adalah memilih satu package manager dan menghapus jejak yang lain:

# Hapus semua lock file dan node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml

# Pilih satu: misalnya npm
npm install

# Tambahkan package manager lain ke .gitignore
echo "yarn.lock" >> .gitignore
echo "pnpm-lock.yaml" >> .gitignore

Baca log dengan teliti

Ketika error muncul, jangan hanya membaca baris pertama. Stack trace yang mengikuti pesan utama biasanya mengandung petunjuk berharga. Perhatikan baris yang menyebutkan file spesifik—misalnya, /path/to/project/postcss.config.js:2:24—karena ini menunjukkan persis di baris dan kolom mana error dipicu. Buka file tersebut dan periksa apa yang ada di posisi itu.

Untuk mendapatkan log yang lebih detail, jalankan perintah dengan flag verbose:

#npm dengan log level verbose
npm run build --loglevel verbose

# Atau gunakan environment variable DEBUG
DEBUG=postcss:* npm run build

Output verbose akan menunjukkan setiap langkah yang PostCSS lakukan, termasuk plugin mana yang berhasil dimuat dan mana yang gagal. Kadang, error sebenarnya bukan di @tailwindcss/postcss itu sendiri, melainkan di plugin PostCSS lain yang gagal dimuat terlebih dahulu, dan pesan error yang muncul hanyalah efek domino.

Cek interaksi dengan framework

Beberapa framework seperti Next.js, Nuxt, atau Astro memiliki konfigurasi PostCSS bawaan yang mungkin berkonflik dengan konfigurasi custom kamu. Next.js, misalnya, membaca postcss.config.js secara otomatis, tetapi jika kamu juga mengkonfigurasi PostCSS di dalam next.config.js, keduanya bisa saling menimpa. Pastikan hanya ada satu sumber konfigurasi PostCSS yang aktif.

// next.config.js — jangan definisikan PostCSS di sini jika sudah ada postcss.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Jangan tambahkan konfigurasi PostCSS di sini
}
module.exports = nextConfig

Sumber resmi

Jika masalah masih berlanjut, ada beberapa sumber resmi yang bisa kamu konsultasikan untuk pemahaman yang lebih mendalam. Pertama, dokumentasi resmi Tailwind CSS v4 di tailwindcss.com menjelaskan secara lengkap cara setup plugin PostCSS yang benar. Kedua, GitHub repository Tailwind CSS di github.com/tailwindlabs/tailwindcss memiliki tab Issues yang bisa kamu cari—kemungkinan besar orang lain sudah mengalami masalah yang sama dan solusinya sudah didokumentasikan. Ketiga, diskusi di GitHub Discussions biasanya lebih interaktif dan bisa kamu gunakan untuk bertanya jika benar-benar menemukan kasus edge case yang belum pernah dilaporkan.

Untuk masalah spesifik terkait PostCSS itu sendiri, dokumentasi resmi PostCSS di postcss.org dan repository github.com/postcss/postcss-load-config menjelaskan bagaimana mekanisme loading konfigurasi bekerja, termasuk urutan pencarian file dan prioritas antara file konfigurasi dan konfigurasi inline di package.json. Pemahaman tentang mekanisme ini sering kali menjadi kunci untuk menyelesaikan masalah konfigurasi yang rumit.

Terakhir, jangan ragu untuk membuat proyek minimal baru dari awal—hanya dengan package.json, postcss.config.js, dan satu file CSS—untuk mengisolasi masalah. Jika error tidak muncul di proyek minimal, berarti ada interaksi dengan dependensi lain di proyek aslimu yang menyebabkan konflik. Pendekatan eliminasi ini, meskipun memakan waktu, sering kali menjadi cara paling efektif untuk menemukan akar masalah yang sulit dilacak.