Membundel dengan Rollup dan tsup untuk Pustaka

Konfigurasi bawaan Vite dioptimalkan untuk aplikasi—memaketkan semuanya, menangani aset, dan menghasilkan index.html. Untuk pustaka komponen, Anda memerlukan keluaran yang berbeda: berkas JavaScript ESM/CJS murni tanpa beban waktu proses, tanpa React yang dipaketkan, serta deklarasi TypeScript yang tepat. Mode pustaka Vite dapat digunakan, tetapi Rollup dan tsup lebih khusus untuk kebutuhan ini.

Rollup telah menjadi pemaket standar untuk pustaka JavaScript selama bertahun-tahun. Rollup menghasilkan keluaran yang bersih dan efisien dengan penghapusan kode yang sangat baik, serta mendukung format keluaran ESM dan CJS. Pengangkatan cakupan milik Rollup menghilangkan beban pembungkus modul, sehingga menghasilkan paket pustaka sekecil mungkin.

tsup adalah pemaket TypeScript tanpa konfigurasi yang didukung oleh esbuild. tsup jauh lebih cepat daripada Rollup—esbuild mengompilasi dalam hitungan mikrodetik, bukan milidetik. Konfigurasi minimalnya: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } secara otomatis menghasilkan kedua format modul dan deklarasi TypeScript.

Opsi inti tsup: entry adalah array berisi berkas titik masuk. format menentukan format keluaran: ['esm', 'cjs']. dts: true menghasilkan berkas deklarasi TypeScript .d.ts di samping keluaran JS. target menetapkan lingkungan JavaScript minimum, yaitu esnext atau es2020. splitting: false menjaga keluaran tetap dalam satu berkas.

esbuild (melalui tsup) mengompilasi 10–100 kali lebih cepat daripada Rollup. Rollup menghasilkan keluaran yang sedikit lebih teroptimasi, dengan tingkat perincian penghapusan kode yang tidak digunakan yang lebih baik dan kontrol lebih besar atas batas potongan. Untuk sebagian besar pustaka komponen, kecepatan tsup lebih unggul selama pengembangan. Untuk mendapatkan kontrol maksimum atas penghapusan kode yang tidak digunakan atau menangani penyiapan dengan banyak titik masuk yang kompleks, Rollup lebih disarankan.

Konfigurasi pembuat bundel yang paling penting untuk pustaka React adalah: jangan pernah membundel React atau ReactDOM. Tandai keduanya sebagai eksternal agar tidak disertakan dalam keluaran Anda. Jika pustaka Anda membundel React, pengguna akan memiliki dua salinan React—satu dari bundel Anda dan satu dari aplikasi mereka. Hal ini merusak semua pengait React karena ada beberapa instans React.

Dalam konfigurasi tsup, gunakan opsi external: external: ['react', 'react-dom']. Dalam konfigurasi Rollup, tetapkan external: ['react', 'react-dom', 'react/jsx-runtime']. Sertakan react/jsx-runtime jika pustaka Anda menggunakan Transformasi JSX. Jadikan juga dependensi rekan lain yang dideklarasikan pustaka Anda sebagai eksternal.

Konfigurasi Rollup minimal untuk pustaka TypeScript memerlukan tiga plugin: @rollup/plugin-typescript untuk kompilasi TypeScript, @rollup/plugin-node-resolve untuk menyelesaikan impor node_modules, dan @rollup/plugin-commonjs untuk mengonversi dependensi CommonJS menjadi ESM dalam bundel. Tambahkan rollup-plugin-dts untuk berkas deklarasi.

Keluaran pustaka dengan dua format yang umum adalah: dist/esm/index.js dan dist/esm/index.d.ts untuk konsumen ESM, serta dist/cjs/index.js dan dist/cjs/index.cjs untuk konsumen CJS. Kolom exports pada package.json memetakan jalur ini ke lingkungan yang sesuai. Berkas deklarasi TypeScript berada berdampingan dengan padanan JS-nya.

Pustaka besar dapat memanfaatkan beberapa titik masuk agar konsumen hanya mengimpor yang mereka perlukan. Contohnya: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Setiap titik masuk mendapatkan berkas keluarannya sendiri. Kolom exports pada package.json memetakan setiap jalur publik ke keluarannya: './utils' → './dist/utils.js'.

Tambahkan perintah kompilasi ke skrip package.json: "build": "tsup". tsup membaca konfigurasinya dari tsup.config.ts di direktori utama. Skrip prapublikasi harus menjalankan kompilasi: "prepublishOnly": "npm run build" memastikan paket Anda selalu dikompilasi sebelum dipublikasikan ke npm.

Mengapa React harus ditandai sebagai eksternal saat membundel pustaka komponen React?

tsup (yang menggunakan esbuild) menyediakan pembundelan cepat tanpa konfigurasi dengan format: ['esm', 'cjs'] dan dts: true. Rollup menawarkan kontrol penghapusan kode yang tidak digunakan dengan tingkat perincian lebih tinggi melalui @rollup/plugin-typescript. Aturan terpenting: selalu tandai react, react-dom, dan semua dependensi rekan sebagai eksternal agar tidak ikut dibundel. Keluarkan hasil ke dist/esm/ dan dist/cjs/ bersama deklarasi TypeScript yang dibuat secara paralel. Beberapa titik masuk memungkinkan penghapusan kode yang lebih terperinci bagi konsumen.