ESM ve CJS Çift Paket Çıktısı

ESM (ECMAScript Modülleri), import ve export söz dizimini kullanan resmî JavaScript modül standardıdır. ESM statik olarak analiz edilebilir; paketleyiciler derleme zamanında tam olarak hangi dışa aktarmaların kullanıldığını belirleyebilir ve böylece ağaç sarsmayı mümkün kılar. Modern tarayıcılar ve Node.js, ESM'yi yerel olarak destekler.

CJS (CommonJS), require() ve module.exports söz dizimini kullanır. Node.js'in özgün modül sistemidir ve daha eski Node.js ortamlarıyla, tarihsel olarak CJS kullanan Jest ile ve require() kullanan kodlarla uyumluluk için hâlâ gereklidir. CJS dinamik olarak değerlendirilir; bu da ağaç sarsmayı zorlaştırır.

Modern bir npm paketi, uyumluluğu en üst düzeye çıkarmak için hem ESM hem de CJS sunmalıdır. ESM kullanıcıları (Vite, Next.js ve modern paketleyiciler) ağaç sarsmaya uygun içe aktarmalar elde eder. CJS kullanıcıları (daha eski Node.js betikleri ve yapılandırma yapılmamış Jest) require() uyumluluğu elde eder. package.json içindeki exports alanı, Node ve paketleyicilere hangi biçimin kullanılacağını bildirir.

package.json içindeki exports alanı, koşullu giriş noktalarını tanımlamanın modern yoludur. Örnek: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Paketleyiciler ve Node.js 12+, doğru biçimi otomatik olarak seçmek için exports alanını okur.

Daha eski araçlar exports alanını anlamaz. Uyumluluk için ayrıca şunları ayarlayın: CJS çıktısını gösteren main alanı (eski Node require geri dönüşü) ve ESM çıktısını gösteren module alanı (webpack/rollup için standart dışı ancak yaygın olarak desteklenen bir ipucu). Modern araçlar exports alanını tercih eder; eski araçlar main/module alanlarına geri döner.

package.json içinde "type": "module" ayarının yapılması, paketteki tüm .js dosyalarının ESM olarak değerlendirilmesini sağlar. İki biçim sunuyorsanız açık uzantılar kullanmanız gerekir: type module iken ESM dosyaları için .mjs, CJS dosyaları için .cjs kullanın veya bunun tersini yapın. tsup bunu otomatik olarak yönetir.

.mjs (ESM) ve .cjs (CJS) dosya uzantılarını açıkça kullanmak, type alanından bağımsız olarak biçimi belirtir. Bu, belirsizliği ortadan kaldırır. type alanı ayarlanmadığında ve biçim ['esm', 'cjs'] olduğunda tsup, en yaygın kullanıma uygun olarak index.js (ESM) ve index.cjs (CJS) çıktısı verebilir.

Bir paket hem ESM hem de CJS biçimleri sağladığında, kullanıcının paketleyicisi her iki sürümü de aynı işlemde yükleyebilir; örneğin ana uygulama için ESM sürümünü, bir Jest sınaması için CJS sürümünü. Pakette modül düzeyinde durum (React bağlamı gibi) varsa iki örneğin de durumu birbirinden bağımsız olur. Buna iki biçimli paket tehlikesi denir.

Tehlikeyi azaltmak için modül düzeyindeki durumu kitaplığınızdan uzak tutun (tekil örüntüler kullanmayın), yalnızca bir biçimin yüklenmesini sağlamak üzere exports koşullarını kesin biçimde kullanın ve sınamaların paketleyicilerini ESM kullanacak şekilde yapılandırması gerektiğini belgelendirin. Bu tehlike esas olarak paylaşılan tekillere sahip kitaplıklar için önemlidir.

Derlemeden sonra her iki biçimin de çalıştığını doğrulayın. CJS'yi sınayın: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". ESM'yi sınayın: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Yayımlamadan önce her ikisi de hatasız çözümlenmelidir.

exports alanı birden çok giriş noktasını destekler: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Kullanıcılar daha sonra 'your-lib' veya 'your-lib/utils' yolundan içe aktarır ve doğru biçimi elde eder.

Bir kitaplığın package.json dosyasındaki exports alanının temel amacı nedir?

ESM, import/export kullanır ve ağaç sarsmayı mümkün kılar. CJS, Node.js uyumluluğu için require() kullanır. Her ikisini de import/require koşullarıyla birlikte package.json içindeki exports alanı aracılığıyla sunun. Eski geri dönüşler: main (CJS) ve module (ESM). Biçimi açıkça belirtmek için .mjs/.cjs uzantılarını veya type: module ayarını kullanın. Derlemeden sonra node CLI aracılığıyla her iki biçimi de sınayın. Tekil durum kullanan iki biçimli paket tehlikesine karşı dikkatli olun.