Kitaplıklar için Rollup ve tsup ile Paketleme

Vite'ın varsayılan yapılandırması uygulamalar için iyileştirilmiştir; her şeyi paketler, varlıkları yönetir ve bir index.html oluşturur. Bir bileşen kitaplığı için farklı bir çıktı gerekir: çalışma zamanı ek yükü olmayan, React'i paketlemeyen saf ESM/CJS JavaScript dosyaları ve uygun TypeScript bildirimleri. Vite kitaplık modu ile çalışabilir, ancak Rollup ve tsup bu amaç için daha uygundur.

Rollup, yıllardır JavaScript kitaplıkları için standart paketleyici olmuştur. Mükemmel ağaç budama desteğiyle temiz ve verimli çıktılar üretir; ayrıca hem ESM hem de CJS çıktı biçimlerini destekler. Rollup'ın kapsam yükseltme özelliği, modül sarmalayıcısı ek yükünü ortadan kaldırarak mümkün olan en küçük kitaplık paketlerini üretir.

tsup, esbuild tarafından desteklenen sıfır yapılandırmalı bir TypeScript paketleyicisidir. Rollup'tan çok daha hızlıdır (esbuild, milisaniyeler yerine mikrosaniyelerde derleme yapar). En az yapılandırmayla şu ayar: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } her iki modül biçimini ve TypeScript bildirimlerini otomatik olarak üretir.

Temel tsup seçenekleri şunlardır: giriş, giriş noktası dosyalarının dizisidir. biçim, çıktı biçimlerini belirtir: ['esm', 'cjs']. bildirim üretme, JS çıktısının yanında .d.ts TypeScript bildirim dosyaları oluşturur. hedef, en düşük JavaScript ortamını belirler (esnext veya es2020). bölme, çıktıyı tek dosyalarda tutar.

esbuild (tsup aracılığıyla), Rollup'tan 10-100 kat daha hızlı derleme yapar. Rollup, daha iyi ağaç sarsma ayrıntı düzeyi ve parça sınırları üzerinde daha fazla denetim sağlayarak biraz daha iyi optimize edilmiş çıktılar üretir. Çoğu bileşen kitaplığında geliştirme sırasında tsup'ın hızı üstün gelir. En üst düzeyde ağaç sarsma denetimi veya karmaşık çoklu giriş yapılandırmaları gerektiğinde Rollup tercih edilir.

Bir React kitaplığı için en kritik paketleyici yapılandırması şudur: React'i veya ReactDOM'u asla paketlemeyin. Çıktınıza dahil edilmemeleri için bunları harici olarak işaretleyin. Kitaplığınız React'i paketlerse kullanıcıların elinde iki React kopyası olur: biri paketinizden, diğeri uygulamalarından gelir. Birden çok React örneği bulunduğundan tüm React kancaları çalışmaz.

tsup yapılandırmasında external seçeneğini kullanın: external: ['react', 'react-dom']. Rollup yapılandırmasında external: ['react', 'react-dom', 'react/jsx-runtime'] ayarını yapın. Kitaplığınız JSX Dönüşümü kullanıyorsa react/jsx-runtime değerini de ekleyin. Kitaplığınızın tanımladığı diğer eş bağımlılıkları da harici olarak işaretleyin.

Bir TypeScript kitaplığı için en küçük Rollup yapılandırması üç eklenti gerektirir: TypeScript derlemesi için @rollup/plugin-typescript, node_modules içe aktarmalarını çözümlemek için @rollup/plugin-node-resolve ve paket içindeki CommonJS bağımlılıklarını ESM'ye dönüştürmek için @rollup/plugin-commonjs. Bildirim dosyaları için rollup-plugin-dts ekleyin.

Tipik bir iki biçimli kitaplık çıktısı şöyledir: ESM kullanıcıları için dist/esm/index.js ve dist/esm/index.d.ts, CJS kullanıcıları için dist/cjs/index.js ve dist/cjs/index.cjs. package.json içindeki exports alanı bu yolları doğru ortamlara eşler. TypeScript bildirim dosyaları, ilgili JS dosyalarının yanında bulunur.

Büyük kitaplıklar, kullanıcıların yalnızca ihtiyaç duyduklarını içe aktarması için birden çok giriş noktasından yararlanır. Örneğin: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Her giriş için kendi çıktı dosyaları oluşturulur. package.json içindeki exports alanı, her genel yolu çıktısına eşler: './utils' → './dist/utils.js'.

Derleme komutunu package.json içindeki betiklere ekleyin: "build": "tsup". tsup, yapılandırmasını kök dizindeki tsup.config.ts dosyasından okur. Ön yayımlama betiği derlemeyi çalıştırmalıdır: "prepublishOnly": "npm run build", paketinizin npm'de yayımlanmadan önce her zaman derlenmesini sağlar.

tsup (esbuild destekli), format: ['esm', 'cjs'] ve dts: true ile hızlı, sıfır yapılandırmalı paketleme sağlar. Rollup, @rollup/plugin-typescript ile daha ayrıntılı ağaç sarsma denetimi sunar. Kritik kural şudur: paketlenmelerini önlemek için react, react-dom ve tüm eş bağımlıkları her zaman harici olarak işaretleyin. Paralel TypeScript bildirimleriyle dist/esm/ ve dist/cjs/ dizinlerine çıktı alın. Birden çok giriş noktası, kullanıcılar için ayrıntılı ağaç sarsmayı mümkün kılar.