- React
İlk npm Paketlerimi Nasıl Yayınladım? usecraft ve motion-kit-css
Küçük bir React hook'u ve JavaScript'siz bir CSS animasyon kütüphanesini sıfırdan yazıp npm'e çıkarırken öğrendiklerim.
Zeynep Baş3 dk okuma
Neden kendi paketimi yazdım?
Her projede aynı kodu kopyalamaktan kurtulmak
Arama kutusu, filtre ya da otomatik kaydetme olan her projede aynı debounce mantığını yeniden yazıyordum. Aynı şey hover efektleri ve degrade metinler için de geçerliydi. Bu parçaları bir kez düzgün yazıp test etmek ve her projede tek komutla kurmak istedim.
Ortaya iki paket çıktı:
usecraft: değeri, kullanıcı yazmayı bırakana kadar bekleten useDebounce hook'u.
motion-kit-css: JavaScript gerektirmeyen, sınıf eklemekle çalışan CSS animasyon efektleri.
usecraft: useDebounce(value, delay)
Her tuşta istek atmayı önleyen küçük bir hook
Hook bir değer ve bekleme süresi alır, varsayılan süre 300 milisaniyedir. İlk render'da değeri olduğu gibi döndürür; sonrasında değer belirtilen süre boyunca değişmeden kaldığında güncellenir.
Kullanım: const debouncedSearch = useDebounce(search, 300);
Değerler Object.is ile karşılaştırılır.
delay değişirse bekleyen zamanlayıcı yeniden başlar.
Bileşen kaldırıldığında zamanlayıcı temizlenir.
Her render'da yeniden oluşan bir nesne ya da dizi yeni değer sayılır ve beklemeyi sıfırlar. Bunu önlemek için değeri useMemo ile saklamak ya da nesneden türetilen ilkel bir değeri debounce etmek gerekir.
React neden peer dependency?
"Invalid hook call" hatasından kaçınmak
Bir hook, kendisini çağıran bileşenle aynı React örneğinde çalışmak zorundadır. React'i normal bağımlılık olarak ekleseydim paket yöneticisi projeye ikinci bir React kopyası kurabilirdi. Bu da hook'ların çalışmamasına ve "Invalid hook call" hatasına yol açar.
Bu yüzden React, peerDependencies altında "react": ">=16.8.0" olarak tanımlı. Paket, uygulamanın zaten kullandığı React sürümüyle çalışır.
motion-kit-css: tek dosya, sıfır JavaScript
Stil dosyasını ekle, sınıfı ver, bitti
motion-kit-css, modern arayüzlerde sık kullandığım efektleri saf CSS ile sunar. Framework ya da yapılandırma gerektirmez.
gradient: animasyonlu degrade metin
shimmer: ışıltılı metin
glow: parlayan metin
border: animasyonlu degrade kenarlık
button-lift ve button-shine: buton hover efektleri
pulse ve underline
Kullanıcının işletim sisteminde hareket azaltma (prefers-reduced-motion) açıksa animasyonlar devre dışı kalır. Erişilebilirlik bir eklenti değil, varsayılan davranış olmalı.
Tamamını import 'motion-kit-css' ile, sadece ihtiyaç duyduğun efekti ise motion-kit-css/glow.css gibi tek dosya olarak içe aktarabilirsin. Küçültülmüş sürüm motion-kit-css/min yolunda.
Paketin içine ne giriyor?
files alanı ve dist klasörü
package.json içindeki files alanı yalnızca dist klasörünü içerir. Kaynak kod, testler ve yapılandırma dosyaları pakete girmez; kullanıcı sadece ihtiyaç duyduğu derlenmiş dosyaları indirir.
usecraft: 4 dosya, yaklaşık 3 kB.
motion-kit-css: 12 dosya, yaklaşık 6 kB.
dist klasörü Git'e eklenmez. prepack betiği, npm pack ve npm publish sırasında build'i otomatik çalıştırır. usecraft Vite ile, motion-kit-css Lightning CSS ile derlenir.
Yayından önce npm pack --dry-run ile paketin içine tam olarak hangi dosyaların gireceğini görmek, yanlışlıkla .env ya da gereksiz klasör yayınlamanın önüne geçer.
Yayından önce otomatik kontroller
prepublishOnly ile kırık sürüm çıkarmamak
prepublishOnly betiği npm publish öncesinde çalışır. Testlerden ya da lint'ten biri hata verirse yayın durur.
usecraft: ESLint ve Vitest ile React Testing Library testleri.
motion-kit-css: Node'un yerleşik test koşucusu (node --test) ile derlenen CSS'in kontrolü.
Paketi gerçek bir projede denemek için npm link yerine npm pack ile üretilen .tgz dosyasını kurmayı tercih ediyorum. Böylece yayınlanacak dosyaların birebir aynısını test etmiş oluyorum ve ikinci bir React kopyası riski azalıyor.
Sürüm yönetimi
Semantic Versioning: MAJOR.MINOR.PATCH
İki paket de Semantic Versioning kurallarını izler. Yeni sürüm npm version patch, minor ya da major ile oluşturulur, ardından npm publish ve git push --follow-tags çalıştırılır.
PATCH: API'yi değiştirmeyen hata düzeltmeleri.
MINOR: geriye dönük uyumlu yeni özellikler.
MAJOR: geriye dönük uyumluluğu bozan değişiklikler.
npm'de yayınlanan bir sürüm 72 saat geçtikten sonra geri çekilemez ve aynı sürüm numarası bir daha kullanılamaz. Bu yüzden yayından önceki kontroller önemli.
Kurulum ve bağlantılar
İkisi de ücretsiz ve açık kaynak
Paketleri tek komutla kurabilirsin:
npm install usecraft
npm install motion-kit-css
Canlı denemeler ve tüm bağlantılar için: https://www.zeynepbas.dev/npm
GitHub: https://github.com/zeynepbass/usecraft
GitHub: https://github.com/zeynepbass/motion-kit
npm: https://www.npmjs.com/package/usecraft
npm: https://www.npmjs.com/package/motion-kit-css