Pesan error cannot find module '@tailwindcss/vite' adalah salah satu error yang paling sering muncul ketika developer mencoba mengintegrasikan Tailwind CSS v4 dengan Vite dalam proyek TypeScript. Error ini bisa muncul di editor, di terminal saat build, atau bahkan keduanya. Artikel ini akan membongkar seluk-beluk error ini dari akar masalahnya hingga cara memastikan ia tidak kembali muncul di proyek kamu.

Anatomi pesan error

Pesan error lengkap yang muncul biasanya terlihat seperti ini:

error TS2307: Cannot find module '@tailwindcss/vite' or its corresponding type declarations.

Atau dalam konteks runtime Vite:

Error: Cannot find module '@tailwindcss/vite'
Require stack:
- /project/vite.config.ts

Kadang-kadang, error ini juga muncul sebagai warning di editor VS Code dengan garis merah di bawah import statement:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite' // ← garis merah di sini

Dalam bahasa Indonesia, pesan ini berarti: TypeScript (atau Node.js resolver) tidak bisa menemukan paket @tailwindcss/vite di dalam node_modules, dan juga tidak bisa menemukan file deklarasi tipe (.d.ts) yang berkorelasi dengan modul tersebut.

Error ini muncul karena ada mekanisme resolusi modul yang gagal. Ketika kamu menulis import tailwindcss from '@tailwindcss/vite', runtime atau compiler akan mencari modul itu melalui serangkaian lokasi: pertama di node_modules/@tailwindcss/vite, lalu naik ke parent directory, dan seterusnya hingga root filesystem. Jika modul tidak ditemukan di mana pun, atau jika modul ada tetapi tidak memiliki package.json yang valid dengan field main, module, atau exports yang benar, maka error ini dilempar.

Untuk konteks TypeScript, layer kedua dari error ini adalah pencarian type declarations. TypeScript mencari file index.d.ts atau path yang dideklarasikan di field types dalam package.json modul tersebut. Jika modul memang tidak terinstal, maka tentu declarations-nya juga tidak ada — sehingga kedua bagian pesan error muncul bersamaan: "cannot find module or its corresponding type declarations."

Penting untuk dipahami bahwa error ini bukan berarti Tailwind CSS itu sendiri rusak. Error ini murni masalah resolusi paket — paket yang kamu referensikan di kode tidak tersedia di lingkungan eksekusi saat ini. Ini mirip dengan mencoba menghubungi nomor telepon yang belum disimpan di kontak: teleponnya ada, tapi kamu belum menyimpan datanya sehingga sistem tidak bisa menghubungkan panggilan itu.

Penyebab umum

Ada beberapa root cause yang bisa memicu error ini, diurutkan dari yang paling sering terjadi di lapangan:

1. Paket @tailwindcss/vite belum diinstal sama sekali. Ini adalah penyebab paling umum. Banyak developer mengikuti tutorial Tailwind CSS v4 yang menampilkan konfigurasi vite.config.ts dengan import @tailwindcss/vite, tetapi melewatkan langkah instalasi paketnya. Mereka menambahkan import di konfigurasi, lalu langsung menjalankan dev server — dan error muncul karena paket memang tidak ada di node_modules. Kamu bisa memastikan ini dengan menjalankan:

ls node_modules/@tailwindcss/vite 2>/dev/null && echo "ADA" || echo "TIDAK ADA"

Jika output-nya "TIDAK ADA", maka paket memang belum terinstal.

2. Menggunakan versi Tailwind CSS yang salah. Paket @tailwindcss/vite hanya tersedia mulai Tailwind CSS v4 ke atas. Jika proyek kamu masih menggunakan Tailwind CSS v3 (yang dikonfigurasi via tailwind.config.js dan PostCSS), maka paket @tailwindcss/vite tidak akan ditemukan karena ia memang tidak ada di ekosistem v3. Developer yang upgrade partial — mengubah vite config tapi tidak mengubah dependensi — sering terkena ini. Cara memastikan:

npm ls tailwindcss

Jika output menunjukkan versi 3.x.x, maka kamu berada di ekosistem yang salah untuk paket ini.

3. node_modules korup atau tidak sinkron dengan package.json. Ini terjadi ketika kamu sudah menambahkan paket di package.json (misalnya via manual edit atau merge conflict resolution) tetapi belum menjalankan npm install. Atau ketika proses npm install sebelumnya terputus di tengah jalan, menyebabkan node_modules dalam keadaan parsial. Kamu juga bisa mengalami ini jika menggunakan monorepo dengan workspace dan resolusi symlink bermasalah. Verifikasi:

# Cek apakah paket terdaftar di package.json tapi tidak ada di node_modules
cat package.json | grep "@tailwindcss/vite"
ls node_modules/@tailwindcss/vite/package.json 2>/dev/null || echo "TIDAK ADA"

Jika grep menemukan entry tapi ls gagal, berarti node_modules tidak sinkron.

4. Versi Node.js yang tidak kompatibel. Paket @tailwindcss/vite membutuhkan Node.js versi minimum tertentu (biasanya >= 18). Jika kamu menjalankan Node.js versi lama, npm install mungkin berhasil tapi paket tidak terinstal dengan benar karena optional dependencies yang gagal diam-diam. Kamu bisa memastikan:

node --version

Jika versi di bawah 18.x, ini kemungkinan penyebabnya.

5. Konflik package manager. Kamu menggunakan pnpm atau yarn di proyek yang sebelumnya menggunakan npm, atau sebaliknya. Setiap package manager menyimpan node_modules dengan struktur berbeda. Jika ada sisa node_modules dari package manager lain, resolusi modul bisa kacau. Khususnya pnpm dengan strict peer dependencies bisa diam-diam tidak menginstal paket jika ada peer dependency conflict. Tanda-tandanya:

# Cek lockfile mana yang ada
ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

Jika ada lebih dari satu lockfile, kamu punya konflik package manager.

Memperbaiki error ini

Mari kita perbaiki error ini langkah demi langkah. Solusi di bawah disusun dari yang paling cepat dan langsung, kemudian dilanjutkan dengan fix permanen berdasarkan root cause.

Langkah 1: Instal paket yang hilang

Ini adalah solusi langsung untuk penyebab #1. Jalankan perintah instalasi sesuai package manager kamu:

# Menggunakan npm
npm install -D @tailwindcss/vite

# Menggunakan yarn
yarn add -D @tailwindcss/vite

# Menggunakan pnpm
pnpm add -D @tailwindcss/vite

# Menggunakan bun
bun add -D @tailwindcss/vite

Output yang diharapkan (contoh npm):

added 1 package, and audited 142 packages in 3s

Setelah instalasi, verifikasi paket sudah ada:

ls node_modules/@tailwindcss/vite/package.json
# Output: node_modules/@tailwindcss/vite/package.json

Langkah 2: Pastikan Tailwind CSS v4 terinstal

Paket @tailwindcss/vite adalah bagian dari ekosistem Tailwind CSS v4. Jika kamu belum menginstal tailwindcss v4, jalankan:

npm install -D tailwindcss@next @tailwindcss/vite@next

Atau jika v4 sudah stabil (bukan next lagi):

npm install -D tailwindcss @tailwindcss/vite

Verifikasi versi:

npx tailwindcss --help
# Output: tailwindcss v4.x.x

Langkah 3: Konfigurasi vite.config.ts dengan benar

Setelah paket terinstal, pastikan konfigurasi Vite kamu benar:

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

Export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

Perhatikan bahwa di Tailwind CSS v4, kamu tidak lagi memerlukan tailwind.config.js atau konfigurasi PostCSS. Semua konfigurasi CSS dilakukan langsung di file CSS menggunakan directive @import:

/* src/style.css */
@import "tailwindcss";

Langkah 4: Bersihkan dan reinstal jika node_modules korup (penyebab #3)

Jika langkah 1-2 tidak memperbaiki masalah, kemungkinan node_modules korup. Lakukan clean reinstall:

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

# Reinstal semua
npm install

# Instal ulang paket Tailwind
npm install -D tailwindcss @tailwindcss/vite

Untuk pnpm, perintahnya sedikit berbeda:

rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm add -D tailwindcss @tailwindcss/vite

Langkah 5: Perbaiki versi Node.js jika perlu (penyebab #4)

# Cek versi saat ini
node --version

# Jika di bawah 18, upgrade menggunakan nvm
nvm install 20
nvm use 20

# Lalu reinstal
rm -rf node_modules
npm install

Verifikasi solusi berhasil

Setelah semua langkah di atas, jalankan dev server untuk memverifikasi:

npm run dev

Output yang diharapkan:

  VITE v6.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Tidak ada error TypeScript, tidak ada error module resolution. Di editor VS Code, garis merah di import statement harusnya sudah hilang. Jika belum, jalankan "TypeScript: Restart TS Server" dari Command Palette (Ctrl+Shift+P).

Mencegah error ini kembali

Memperbaiki error sekali tidak cukup — kamu perlu memastikan bahwa error ini tidak muncul kembali di masa depan, baik di mesin kamu sendiri maupun di mesin rekan kerja atau CI/CD pipeline.

Pin versi di package.json

Gunakan exact version atau range yang ketat untuk menghindari breaking change diam-diam:

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

Perhatikan bahwa tailwindcss dan @tailwindcss/vite harus memiliki versi yang selaras. Jika kamu menggunakan versi yang tidak match, bisa terjadi runtime error yang lebih sulit di-debug. Commit lockfile kamu ke repository:

git add package-lock.json
git commit -m "chore: lock tailwindcss v4 dependencies"

Gunakan engines field di package.json

Untuk mencegah developer menggunakan Node.js versi lama yang bisa menyebabkan instalasi gagal:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Kombinasikan dengan .nvmrc untuk konsistensi:

# .nvmrc
20

Konfigurasi TypeScript yang tepat

Pastikan tsconfig.json kamu memiliki konfigurasi yang mendukung resolusi modul Vite dengan benar:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["vite/client"]
  }
}

Penggunaan moduleResolution: "bundler" sangat penting di sini. Mode ini mengizinkan TypeScript untuk memahami package exports yang digunakan oleh paket-paket modern seperti @tailwindcss/vite. Mode lama seperti "node" atau "node16" bisa gagal meresolve paket yang menggunakan conditional exports di package.json.

Perbedaan antar OS

Di Windows, ada beberapa hal yang perlu diperhatikan. Pertama, perintah rm -rf tidak tersedia di Command Prompt atau PowerShell. Gunakan alternatif:

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

Kedua, di Windows, path length bisa menjadi masalah. Jika node_modules nested terlalu dalam, npm bisa gagal menginstal paket dengan diam-diam. Solusinya, aktifkan long path support atau gunakan hoisted node_modules:

# .npmrc
shamefully-hoist=true

Atau untuk pnpm:

# .npmrc
shamefully-hoist=true

Di macOS dan Linux, path length bukan masalah, tapi permission bisa. Jika kamu menjalankan npm install dengan sudo, file-file di node_modules bisa dimiliki root, dan subsequent install bisa gagal:

# Perbaiki ownership
sudo chown -R $(whoami) node_modules

CI/CD pipeline check

Tambahkan step di CI untuk memastikan dependensi terinstal dengan benar:

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npx tsc --noEmit
      - run: npm run build

Step npx tsc --noEmit akan menangkap error "cannot find module" sebelum kode masuk ke production. Step npm ci (bukan npm install) memastikan instalasi sesuai lockfile secara strict — jika ada ketidakcocokan, CI akan gagal, memberi sinyal bahwa ada masalah dependensi.

Langkah lanjutan

Jika semua solusi di atas sudah kamu coba dan error masih muncul, ada beberapa kemungkinan yang lebih niche yang perlu diselidiki.

Debug resolusi modul

TypeScript memiliki flag --traceResolution yang menunjukkan secara detail bagaimana ia mencari modul:

npx tsc --traceResolution 2>&1 | grep "@tailwindcss/vite"

Output-nya akan terlihat seperti:

======== Resolving module '@tailwindcss/vite' from 'vite.config.ts'. ========
Module resolution kind: bundler
Loading module as file / folder, candidate module location '/project/node_modules/@tailwindcss/vite'.
File '/project/node_modules/@tailwindcss/vite.ts' does not exist.
File '/project/node_modules/@tailwindcss/vite.tsx' does not exist.
File '/project/node_modules/@tailwindcss/vite.d.ts' does not exist.
...
======== Module '@tailwindcss/vite' was not resolved. ========

Dari trace ini kamu bisa melihat persis di mana resolusi gagal. Mungkin TypeScript mencari di path yang salah, atau node_modules yang diperiksa bukan yang kamu kira.

Cek apakah ada tsconfig yang override

Dalam proyek yang lebih kompleks, bisa ada tsconfig.node.json yang secara eksplisit meng-exclude vite.config.ts dari scope TypeScript, atau menggunakan references yang tidak menyertakan dependensi yang benar:

// tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "Bundler"
  },
  "include": ["vite.config.ts"]
}

Pastikan file konfigurasi Vite di-include di tsconfig yang memiliki akses ke node_modules/@tailwindcss/vite.

Baca log npm install secara verbose

Jika instalasi tampak berhasil tapi paket tidak ada, jalankan instalasi dengan flag verbose:

npm install -D @tailwindcss/vite --loglevel verbose

Perhatikan baris-baris yang mengandung kata "WARN", "ERR", atau "skipping". Kadang npm me-skip paket karena optional dependency yang gagal, dan ini tidak ditampilkan di mode default.

Monorepo dan workspace

Jika kamu menggunakan monorepo (misalnya dengan Turborepo, Nx, atau npm workspaces), paket mungkin terinstal di node_modules root workspace, bukan di node_modules proyek individual. Pastikan resolusi modul TypeScript bisa menemukan paket di parent node_modules:

// tsconfig.json di sub-proyek
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "paths": {
      "@tailwindcss/vite": ["../node_modules/@tailwindcss/vite"]
    }
  }
}

Sumber resmi untuk deep-dive

Jika kamu masih stuck, berikut sumber resmi yang bisa membantu:

  1. Dokumentasi resmi Tailwind CSS v4: https://tailwindcss.com/docs/installation/vite — Panduan instalasi resmi yang selalu up-to-date dengan versi terbaru.

  2. Dokumentasi TypeScript module resolution: https://www.typescriptlang.org/docs/handbook/module-resolution.html — Memahami bagaimana TypeScript mencari modul akan membantu kamu debug masalah resolusi apapun, bukan hanya ini.

  3. Repositori GitHub Tailwind CSS: https://github.com/tailwindcss/tailwindcss — Cek Issues untuk melihat apakah orang lain mengalami masalah yang sama. Seringkali sudah ada workaround atau fix di main branch yang belum di-release.

  4. Dokumentasi Vite: https://vite.dev/guide/using-plugins.html — Memahami cara kerja Vite plugin akan membantu kamu memahami mengapa konfigurasi harus ditulis dengan cara tertentu.

  5. npm docs tentang package resolution: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#exports — Memahami field exports di package.json membantu debug masalah ketika paket terinstal tapi TypeScript tidak bisa meresolve type declarations-nya.

Error cannot find module '@tailwindcss/vite' pada dasarnya adalah error resolusi yang straightforward — paket yang dirujuk tidak tersedia di lingkungan eksekusi. Dalam mayoritas kasus, solusinya sesimpel menjalankan npm install -D @tailwindcss/vite. Namun memahami mengapa paket tidak ditemukan, dan memastikan infrastruktur proyek kamu mendukung resolusi modul yang andal, akan menghemat waktu kamu dari error serupa di masa depan — tidak hanya untuk paket ini, tapi untuk dependensi apapun yang kamu tambahkan ke proyek.