Output Paket Ganda ESM dan CJS

ESM (Modul ECMAScript) adalah standar modul resmi JavaScript yang menggunakan sintaks import dan export. ESM dapat dianalisis secara statis—pembuat bundel dapat menentukan dengan tepat ekspor mana yang digunakan saat proses kompilasi, sehingga memungkinkan penghapusan kode yang tidak digunakan. Peramban modern dan Node.js sama-sama mendukung ESM secara bawaan.

CJS (CommonJS) menggunakan sintaks require() dan module.exports. CJS adalah sistem modul asli Node.js dan masih diperlukan untuk kompatibilitas dengan lingkungan Node.js lama, Jest (yang secara historis menggunakan CJS), serta kode yang menggunakan require(). CJS dievaluasi secara dinamis sehingga penghapusan kode yang tidak digunakan menjadi lebih sulit.

Paket npm modern sebaiknya menyediakan ESM dan CJS untuk memaksimalkan kompatibilitas. Konsumen ESM (Vite, Next.js, dan pembuat bundel modern) mendapatkan impor yang dapat dihapus ketika tidak digunakan. Konsumen CJS (skrip Node.js lama dan Jest tanpa konfigurasi) mendapatkan kompatibilitas dengan require(). Kolom exports pada package.json memberi tahu Node dan pembuat bundel format mana yang harus digunakan.

Kolom exports dalam package.json adalah cara modern untuk menentukan titik masuk bersyarat. Contoh: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Pembuat bundel dan Node.js 12+ membaca exports untuk memilih format yang sesuai secara otomatis.

Peralatan lama tidak memahami kolom exports. Untuk kompatibilitas, tetapkan juga: main yang menunjuk ke keluaran CJS (cadangan require Node lama), dan module yang menunjuk ke keluaran ESM (petunjuk untuk webpack/Rollup, tidak standar tetapi didukung secara luas). Peralatan modern lebih memilih exports, sedangkan peralatan lama menggunakan main/module sebagai cadangan.

Menetapkan "type": "module" dalam package.json membuat semua berkas .js dalam paket diperlakukan sebagai ESM. Jika Anda menyediakan dua format, Anda kemudian memerlukan ekstensi eksplisit: gunakan .mjs untuk berkas ESM dan .cjs untuk berkas CJS saat type bernilai module, atau sebaliknya. tsup menangani hal ini secara otomatis.

Menggunakan ekstensi berkas .mjs (ESM) dan .cjs (CJS) secara eksplisit menandai format, apa pun nilai kolom type. Hal ini menghindari ketidakjelasan. tsup dapat menghasilkan: index.js (ESM) dan index.cjs (CJS) saat formatnya ['esm', 'cjs'] dan kolom type tidak ditetapkan, sesuai dengan konvensi yang paling umum.

Saat sebuah paket menyediakan format ESM dan CJS, pembuat bundel konsumen mungkin memuat kedua versi dalam proses yang sama—misalnya, versi ESM untuk aplikasi utama dan versi CJS untuk pengujian Jest. Jika paket tersebut memiliki status tingkat modul (seperti konteks React), kedua instans memiliki status yang terpisah. Inilah yang disebut bahaya paket ganda.

Untuk mengurangi bahaya ini: jangan simpan status tingkat modul dalam pustaka Anda (hindari pola instans tunggal), gunakan kondisi exports secara tepat untuk memastikan hanya satu format yang dimuat, dan dokumentasikan bahwa pengujian harus mengonfigurasi pembuat bundelnya agar menggunakan ESM. Bahaya ini terutama menjadi masalah bagi pustaka yang memiliki instans tunggal bersama.

Pastikan kedua format berfungsi setelah kompilasi. Uji CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Uji ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Keduanya harus dapat ditemukan tanpa kesalahan sebelum dipublikasikan.

Kolom exports mendukung beberapa titik masuk: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Konsumen kemudian mengimpor dari 'your-lib' atau 'your-lib/utils' dan mendapatkan format yang sesuai.

ESM menggunakan import/export dan memungkinkan penghapusan kode yang tidak digunakan. CJS menggunakan require() untuk kompatibilitas Node.js. Sediakan keduanya melalui kolom exports pada package.json dengan kondisi import/require. Cadangan untuk peralatan lama: main (CJS) dan module (ESM). Gunakan ekstensi .mjs/.cjs atau type: module untuk menandai format secara eksplisit. Uji kedua format dengan CLI node setelah kompilasi. Waspadai bahaya paket ganda yang melibatkan status instans tunggal.