Ringkasan solusi

Untuk proyek Tailwind CSS v4 dengan Vite, pastikan tailwindcss dan @tailwindcss/vite terpasang di paket/workspace yang memiliki konfigurasi Vite, sesuai integrasi resmi Tailwind dengan Vite. Jika paket sudah terpasang tetapi hanya TypeScript yang mengeluh, periksa konfigurasi resolusi modul yang benar-benar mencakup vite.config.ts.

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

Pesan ini tidak membuktikan paket hilang: paket bisa ada tetapi ekspor atau deklarasi tipenya tidak dapat diresolusi oleh konfigurasi aktif. Bedakan kegagalan instalasi, kegagalan memuat konfigurasi Vite, dan diagnosis editor sebelum mengubah dependensi.

Panduan ini membahas Tailwind CSS v4 dan TypeScript 5.x. Proyek Tailwind v3 memiliki alur PostCSS berbeda; jangan menambahkan plugin v4 ke konfigurasi v3 tanpa merencanakan migrasi. Versi Node.js harus memenuhi persyaratan Vite dan plugin yang Anda pilih, bukan angka minimum tunggal untuk semua versi.

1. Periksa paket dan lingkungan yang dipakai

Jalankan dari direktori aplikasi yang memiliki package.json dan konfigurasi Vite:

node --version
npm --version
npm ls tailwindcss @tailwindcss/vite vite typescript

npm ls menunjukkan versi, paket hilang, atau dependensi tidak valid; exit code nonzero perlu ditelusuri, bukan diabaikan. Untuk npm workspace, jalankan pemeriksaan pada workspace aplikasi yang relevan. Paket yang tersedia di root belum tentu sudah dideklarasikan sebagai dependensi aplikasi tersebut.

Jika instalasi sebelumnya gagal, baca error pertamanya, termasuk persyaratan engines dan peer dependencies. Versi Node yang tidak cocok dapat menyebabkan instalasi atau eksekusi gagal; jangan menyimpulkan npm diam-diam berhasil memasang paket rusak.

Gunakan package manager yang ditetapkan proyek dan lockfile miliknya. Adanya beberapa lockfile adalah sinyal untuk diperiksa, bukan bukti otomatis adanya konflik. Jangan mengganti package manager atau menghapus lockfile hanya untuk mencoba-coba.

2. Pasang integrasi Tailwind v4 yang sesuai

Untuk proyek Vite yang memang menggunakan Tailwind v4, pilih satu perintah sesuai package manager:

# npm
npm install -D tailwindcss@4 @tailwindcss/vite@4

# pnpm
pnpm add -D tailwindcss@4 @tailwindcss/vite@4

# Yarn
yarn add -D tailwindcss@4 @tailwindcss/vite@4

Pada npm monorepo, opsi --workspace <nama-workspace> dapat menargetkan aplikasi yang tepat; ganti placeholder dengan nama workspace sebenarnya. Simpan perubahan manifest dan lockfile bersama setelah diperiksa. Pemilihan versi @4 membatasi major version, sedangkan versi tepat yang terpasang ditentukan lockfile.

Tahap build harus memasang devDependencies. Jika CI hanya menginstal dependensi produksi lalu mencoba menjalankan Vite, plugin build bisa tidak tersedia. Pisahkan tahap build dari runtime sesuai platform deployment Anda.

Jangan campur tiga jalur integrasi

Kebutuhan Paket integrasi Tailwind v4
Build menggunakan Vite @tailwindcss/vite
Build melalui PostCSS @tailwindcss/postcss
Menjalankan CLI Tailwind langsung @tailwindcss/cli

Paket inti tailwindcss v4 tidak menyediakan CLI lama. Karena itu, memanggil CLI lama bukan cara memverifikasi instalasi plugin Vite. Gunakan npm ls untuk versi. Jangan memasang deklarasi @types fiktif: plugin membawa tipenya sendiri.

Untuk proyek yang tetap di Tailwind v3, lepaskan import plugin v4 yang baru ditambahkan dan pertahankan integrasi PostCSS v3. Migrasi ke v4 mencakup CSS dan perubahan kompatibilitas, bukan hanya mengganti satu baris import.

3. Hubungkan plugin dan CSS

Contoh minimum untuk proyek Vite biasa:

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

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

export harus huruf kecil. Jika aplikasi memakai React, Vue, atau plugin lain, tambahkan tailwindcss() ke array yang ada; jangan menimpa plugin framework.

Buat atau sesuaikan CSS utama:

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

Lalu impor CSS tersebut dari entry aplikasi:

// src/main.ts
import './style.css';

Contoh ini tidak membutuhkan file konfigurasi Tailwind JavaScript. Itu bukan berarti semua konfigurasi lama otomatis diabaikan dengan aman: jika migrasi masih memakai konfigurasi JavaScript, periksa dukungan dan pemuatan eksplisit melalui @config di panduan migrasi. Plugin PostCSS lain yang tidak terkait Tailwind juga tidak perlu dihapus.

Jika Vite melaporkan paket ESM sedang dimuat lewat require, itu masalah format konfigurasi yang berbeda dari TS2307. Periksa mode ESM proyek dan dokumentasi Vite; menggunakan vite.config.mts dapat menandai konfigurasi sebagai ESM tanpa mengubah tipe semua file .js dalam proyek.

4. Jika paket ada tetapi TypeScript masih gagal

Di template Vite, konfigurasi aplikasi dan konfigurasi Node sering terpisah. Mengubah tsconfig.app.json tidak membantu bila error berasal dari vite.config.ts yang ditangani tsconfig.node.json.

Berikut contoh minimum tsconfig.node.json untuk konfigurasi yang diproses bundler (bukan pengganti semua opsi proyek):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "noEmit": true,
    "types": ["node"]
  },
  "include": ["vite.config.ts"]
}

types: ["node"] membutuhkan @types/node di devDependencies. Jika konfigurasi bernama vite.config.mts, sesuaikan include. Pertahankan opsi dan project references lain yang masih diperlukan.

Menurut referensi TypeScript, TypeScript 5.x dengan moduleResolution: "bundler" memahami package exports dan cocok untuk alur bundler. Node16 dan NodeNext juga memahami exports; keduanya bukan resolver usang seperti mode node/node10. Untuk file yang dieksekusi langsung oleh Node, gunakan pasangan mode Node yang konsisten, misalnya module: "NodeNext" bersama moduleResolution: "NodeNext", serta format ESM/CJS yang sesuai.

Periksa konfigurasi efektif dan jejak resolusi:

npm exec --no -- tsc --showConfig -p tsconfig.node.json
npm exec --no -- tsc --noEmit -p tsconfig.node.json --traceResolution

Perintah ini mengasumsikan TypeScript sudah terpasang lokal. Cari resolusi @tailwindcss/vite, file sumber pemanggil, dan kondisi ekspor yang dipilih. Jangan menambahkan alias menuju ../node_modules atau deklarasi kosong declare module untuk menghilangkan garis merah: keduanya dapat menyembunyikan penyebab tanpa memperbaiki runtime.

Jika CLI berhasil tetapi editor masih mengeluh, pilih TypeScript workspace di editor lalu restart TS Server. Restart editor bukan pengganti memperbaiki konfigurasi atau dependensi yang memang hilang.

5. Verifikasi tanpa membuang lockfile

Jika manifest dan lockfile sudah sinkron tetapi instalasi lokal tidak lengkap, npm ci dapat menginstal ulang sesuai lockfile. Perintah ini mengganti isi node_modules, sehingga gunakan hanya setelah memastikan tidak ada perubahan manual yang perlu disimpan. Jika manifest belum sinkron, perbaiki dependensi dengan instalasi terarah dan tinjau diff lockfile terlebih dahulu.

Setelah paket, konfigurasi, dan CSS benar:

npm ls tailwindcss @tailwindcss/vite vite typescript
npm exec --no -- tsc --noEmit -p tsconfig.node.json
npm run build
npm run dev

Jalankan satu per satu. build dan dev harus memang tersedia di scripts aplikasi. Pada proyek dengan project references, jalankan pula script typecheck proyek yang sesuai; Vite sendiri mentranspilasi TypeScript tetapi bukan pengganti pemeriksaan tipe lengkap.

Uji utility sederhana di markup, misalnya class="text-3xl font-bold" pada HTML atau className="text-3xl font-bold" pada JSX. Pastikan CSS masuk ke hasil build dan gaya terlihat di browser. Dev server yang menyala saja tidak membuktikan CSS diimpor atau semua tipe sudah benar.

Batas verifikasi

Revisi lokal 11 September 2026 memperbaiki sintaks, alur v4/CLI, dan penjelasan resolver. Snippet konfigurasi, CSS, dan entry di atas diuji dalam fixture sementara Windows x64 dengan Node 24.12.0, Vite 8.2.2, Tailwind CSS/plugin Vite 4.3.3, TypeScript 5.9.3, dan @types/node 22.20.1. Instalasi memakai cache npm offline; typecheck dan build berhasil, serta CSS hasil build memuat utility text-3xl dan font-bold yang ditautkan dari HTML.

Review independen pada tanggal yang sama mengulang fixture tersebut: typecheck, build, serta pemeriksaan utility CSS kembali berhasil. Dokumentasi Tailwind, Vite, TypeScript, dan npm di bawah juga diperiksa daring. Uji ini tidak mencakup tampilan browser, dev server, plugin framework, atau semua konfigurasi workspace. Hasilnya bukan jaminan untuk kombinasi versi lain; periksa persyaratan paket terpasang dan jalankan kembali pemeriksaan di proyek Anda.

Sumber resmi

Rujukan berikut diperiksa secara daring pada 11 September 2026; versi paket dalam fixture tetap menjadi batas bukti runtime: