Eş Düzey Bağımlılıklar ve Ağaç Sarsma

Eş bağımlılıklar, kitaplığınızın ihtiyaç duyduğu ancak kullanıcıya sağlamasını beklediği paketleri bildirir. Kitaplığınızın package.json dosyasında React, dependencies yerine peerDependencies içinde yer almalıdır. Kullanıcı kitaplığınızı yüklediğinde npm/yarn React'i otomatik olarak yüklemez; kullanıcının uygulamasında zaten React vardır ve kitaplığınız bu örneği paylaşır.

React, kitaplığınızın dependencies alanındaysa npm, kullanıcının React'inin yanına ikinci bir React kopyası yükleyebilir. Aynı uygulamadaki iki React örneği, tüm kancaları "Invalid hook call" hatasıyla bozar. React'i bir peerDependency olarak bildirerek npm'e "React'e ihtiyacım var, ancak kullanıcının zaten sahip olduğu sürümü kullanın" demiş olursunuz.

Bazı eş bağımlılıklar isteğe bağlı olabilir; örneğin hem styled-components hem de CSS Modules destekleyen bir kitaplık. İsteğe bağlı eş bağımlılıkları peerDependenciesMeta kullanarak işaretleyin: { 'styled-components': { optional: true } }. npm, eksik isteğe bağlı eş bağımlılıklar konusunda kullanıcıları uyarmaz; ancak isteğe bağlı paket yüklendiğinde TypeScript türleri yine sağlanabilir.

package.json içindeki sideEffects alanı, paketleyicilere kitaplığınızın ağaç sarsma için güvenli olup olmadığını bildirir. "sideEffects": false ayarı, webpack, Rollup ve benzeri araçlara kitaplığınızdaki herhangi bir modülü içe aktarmanın yan etkilere yol açmadığını bildirir; kullanılmayan tüm dışa aktarmalar kullanıcının paketinden güvenle çıkarılabilir.

CSS içe aktarmaları yaygın bir yan etkidir; içe aktarıldıklarında sayfaya stil eklerler. Kitaplığınız CSS dosyalarını içe aktarıyorsa paketleyicilere JS dosyalarının güvenle ağaç sarsılabileceğini, ancak CSS dosyalarının içe aktarıldıklarında her zaman dahil edilmesi gerektiğini bildirmek için "sideEffects": ["*.css", "*.scss"] ayarını yapın.

Ağaç sarsmayı en üst düzeye çıkarmak için her bileşeni kendi dosyasından adlandırılmış dışa aktarma olarak sunun. index.ts dosyanızda her şeyi yeniden dışa aktarın: export { Button } from './Button'. Kullanıcı yalnızca Button'ı içe aktardığında paketleyici diğer tüm bileşenleri kaldırabilir. Yeniden dışa aktarmalar içeren toplama dosyaları bu yaklaşımı mümkün kılar.

Ağaç sarsmayı sınamak için bundlejs.com kullanın: içe aktarma ifadenizi yapıştırdığınızda gerçek paket boyutunu bildirir. size-limit npm paketi, package.json dosyanızda boyut bütçeleri tanımlamanıza ve içe aktarma boyutu sınırı aşarsa sürekli tümleştirme sürecini başarısız kılmanıza olanak tanır: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Kitaplığınızın içe aktarmaları için bir boyut bütçesi belirleyin. Bu bütçeyi zorunlu kılmak için sürekli tümleştirme sürecinde npx size-limit komutunu çalıştırın. Paket etkisinin zamanla büyümesi, kapsamın kontrolden çıkarak genişlediğini gösterir. Odaklanmış bir bileşen kitaplığı, tek tek bileşen içe aktarmalarını birkaç kilobaytın altında tutmalıdır. Gerilemeler kullanıcılara ulaşmadan önce bunlar için uyarı verin.

Dağıtmayı planladığınız bileşen kitaplıklarında styled-components ve Emotion kullanmaktan kaçının. Bu çalışma zamanı CSS-in-JS çözümleri, kullanıcının aynı kitaplığı ve sürümü yüklemesini gerektirerek eş bağımlılık çakışmaları oluşturur. Kullanıcının uygulaması Tailwind veya düz CSS kullanıyorsa çalışma zamanı CSS-in-JS çözümünü yine de paketlemek zorundadır. Derleme zamanında düz CSS'ye dönüştürülen CSS Modules'ı tercih edin.

CSS Modules, bunları işleyen bir paketleyiciyle birlikte kullanıldığında kitaplıklarda iyi çalışır. tsup ve Rollup, CSS Modules çıktısını kapsamı sınırlandırılmış sınıf adları olarak doğrudan ekleyebilir. Kullanıcının herhangi bir yapılandırma yapması gerekmez; stiller zaten kapsamı sınırlandırılmış durumdadır ve JS paketine dahil edilir veya içe aktarılan ayrı bir CSS dosyası olarak sunulur.

Kendi geliştirme araçlarınız (tsup, TypeScript, sınama kitaplıkları ve Storybook) devDependencies içinde yer alır; bunlara yalnızca geliştirme sırasında ihtiyaç duyulur ve kullanıcılar için npm install işleminden çıkarılır. React hem çalışma zamanı gereksinimi olarak peerDependencies hem de kitaplığınızı yerel olarak derlemek ve sınamak için gereken devDependencies içinde yer alır.

Bir kitaplığın package.json dosyasında "sideEffects": false ayarının yapılması paketleyicilere ne bildirir?

Kullanıcıların uygulamalarındaki React örneğini paylaşmak için React'i dependencies yerine peerDependencies içinde bildirin. sideEffects: false, kitaplığınızın tamamen ağaç sarsılmasını sağlar. CSS içe aktarmalarının kaldırılmasını önlemek için sideEffects: ['*.css'] kullanın. Tek tek dosyalardaki adlandırılmış dışa aktarmalar, ağaç sarsma ayrıntı düzeyini en üst düzeye çıkarır. Sürekli tümleştirme sürecinde size-limit ile bir boyut bütçesini zorunlu kılın. Eş bağımlılık çakışmalarını önlemek için kitaplıklarda CSS-in-JS yerine CSS Modules'ı tercih edin.