Package.json Diff: npm manifestlerini çevrimiçi karşılaştırın
Eski package.json'u sola, yenisini sağa yapıştırın ve hangi dependencies, scripts ve engines'in değiştiğini tam olarak görün. Tarayıcınızda çalışır, hiçbir şey yüklenmez.
Bu package.json diff aracı nedir
İki npm package.json dosyasını yan yana karşılaştırmak için tarayıcı içinde çalışan ücretsiz bir araç. Eski manifesti sola, yenisini sağa yapıştırın ve farklılıklar karakter karakter vurgulanır. Metin asla makinenizden çıkmaz, bu da manifest özel bir repoya veya yayımlanmamış bir ürüne aitse önemlidir.
Bir Renovate veya Dependabot PR'ı düştüğünde ve sürüm bump'larının ötesinde gerçekten neyin değiştiğini bilmeniz gereken o an için yapıldı. Biri script düzenlemesini araya soktu mu? engines alanı Node 18'den Node 20'ye mi taşındı? Bir peerDependency sıkıldı mı? GitHub'ın diff görünümü bunun bir kısmını yanıtlar, ama birden fazla PR'ı arka arkaya tarıyorsanız veya henüz push edilmemiş dalları karşılaştırıyorsanız iki manifesti temiz bir iki bölmeli görünüme yapıştırmak daha hızlıdır.
Altta, bu, compare-json sayfamızı çalıştıran aynı JSON farkındalıklı diff'tir, çerçeveleme ve metin npm ve yarn iş akışlarına ayarlanmıştır. Diff çalışmadan önce her iki manifest de JSON olarak parse edilir ve düzgün biçimlendirilir, böylece kozmetik boşluk farklılıkları vurguyu kirletmez. JSON dışı bir manifest formatı için ham metin diff'ine ihtiyacınız varsa compare-text aracımız bunu kapsar ve compare-yaml pnpm-lock.yaml'ı işler.
Diff gerçekte nasıl çalışır
Her bölme JSON olarak parse edilir. Parse başarılı olursa, manifest tutarlı iki boşluklu girinti ile yeniden biçimlendirilir ve anahtar sırası yazıldığı gibi korunur. Parse başarısız olursa (kayıp bir virgül, eksik bir küme parantezi, çok az karakter yakalayan bir kopyala-yapıştır) araç düz metin moduna geri döner ve hangi satırın bozulduğunu söyler. İki taraf da geçerli JSON olduğunda, diff karakter karakter çalışır, sonra bir semantik temizleme geçişi değişiklikleri okunabilir parçalara yeniden gruplar, böylece ^18.2.0'dan ^19.0.0'a bir sürüm bump'ı dokuz karakter düzenlemesi olarak değil bir düzenleme olarak okunur.
Sağ bölmedeki eklemeler yeşil; sol bölmedeki silmeler kırmızı render edilir. İki bölme birlikte kaydırma kilidine sahiptir, bu yüzden bir tarafta devDependencies'in derinliklerinde bir değişiklik bulduğunuzda, diğer taraf aynı anahtara atlar. Diff düzgün biçimlendirme sonrası metin seviyesinde olduğundan, yapısal değişiklikleri bir insanın okuduğu gibi görür: kaldırılmış bir bağımlılık satır olarak kaybolur, değişmiş bir semver aralığı değer içinde vurgulanır, yeni bir script yerleştirdiğiniz konumda scripts bloğuna oturur.
Aracın bilerek yapmadığı şey: bağımlılık çözümleyicisi değildir. Bir caret aralığı bump'ının hangi geçişli paketleri çektiğini, bir peer'in karşılanıp karşılanmadığını veya yeni sürümün bir güvenlik tavsiyesi sunup sunmadığını söylemez. Bunun için yerelde npm install ardından npm audit çalıştırın veya Snyk ya da GitHub'ın Dependabot uyarıları gibi lockfile farkındalıklı bir hizmetle npm kullanın. Bu sayfa size manifest metninin ne dediğini söyler. Çözümleme işi paket yöneticinize aittir.
Üç adımda bir package.json diff'i nasıl yapılır
İki metin bölmesi, bir diff. CLI bayrağı yok, kurulum adımı yok, okunacak yama formatı yok.
- 1
Eski manifesti sola yapıştırın
package.json'un önceki sürümünü editörünüzden, git show main:package.json'dan veya bir takım arkadaşınızdan kopyalayın. Sol bölmeye yapıştırın. Araç onu JSON olarak parse edip düzgün biçimlendirir; JSON geçersizse, editör parse hatasını yüzeye çıkarır, böylece diff yapmadan önce snippet'i düzeltebilirsiniz.
- 2
Yeni manifesti sağa yapıştırın
Güncellenmiş sürümle aynısını yapın. Bir Renovate veya Dependabot PR'ı inceliyorsanız, en kolay kaynak PR dalından ham dosyadır. Her iki dosya tutarlı girinti ile düzgün biçimlendirilir, böylece kozmetik boşluk düzenlemeleri diff'te sahte değişiklikler olarak görünmez.
- 3
Vurgulanan farklılıkları okuyun
Silmeler solda kırmızı üstüçizili olarak; eklemeler sağda yeşil olarak gösterilir. Önce bağımlılık bloklarını tarayın, sonra komut düzenlemeleri için scripts bölümünü kontrol edin, sonra engines ve peerDependencies alanlarını. Tek bir değer içindeki sürüm bump'ları değişen karakterleri vurgular, böylece bir patch bump'ı bir major'dan tek bakışta ayırt edebilirsiniz.
Package.json diff'i ne zaman doğru çağrıdır
Bir Renovate veya Dependabot PR'ını incelemek
Bir bot bir sabahta on beş PR açar. Çoğu rutindir, ama biri bir script değişikliği, sıkılmış bir peerDependency veya CI imajınızı kıran bir engines bump'ını araya sokmuştur. PR başlığı "chore(deps): bump foo from 4.1.0 to 4.2.1" der ve otomatik pilotta güvenirsiniz. Önce-ve-sonra package.json'u diff'e yapıştırın ve beş saniyede başka hiçbir şeyin hareket etmediğini doğrulayabilirsiniz. Bu, JS mühendislerinin bir manifest diff'ine uzanmasının en yaygın tek nedenidir.
Birleştirmeden önce iki dalı karşılaştırmak
Siz ve bir meslektaşınız ayrı feature dallarında package.json'a dokundunuz. Düzenlemeler farklı bloklarda olduğu için Git temiz birleştirir, ama temiz bir birleştirme doğru bir birleştirme demek değildir. Bir dalın düşürdüğü bir script'i, bir dalın downgrade ettiği bir bağımlılığı veya her iki dalın aynı paketi farklı sürümlerde eklediği bir çakışmayı tespit etmek için iki dalın manifestlerini diff'e yapıştırın. CI birleştirilmiş sonuca karşı npm ci çalıştırdıktan sonra keşfetmekten daha ucuz.
npm install'in package-lock.json'da neyi terfi ettirdiğini denetlemek
package.json'u düzenlemek değişikliğin yarısıdır. Diğer yarısı package-lock.json'un çözülmüş ağaç hakkında kaydettiklerdir. npm install çalıştırdıktan sonra, hangi geçişli paketlerin gezintiye geldiğini görmek için eski lockfile'ı yeninin yanına yapıştırın. Caret aralığı derinden iç içe bir bağımlılığın yeni minor'unu çektiğinde sürpriz eklemeler yaygındır. Ham lockfile incelemesi için compare-json sayfamız daha büyük dosyaları daha iyi işler; bu sayfa manifestin kendisi için en iyisidir.
Bir regresyondan sonra downgrade kontrol etmek
Bir release çıkar, bir bug ortaya çıkar, bisect yaparsınız ve şüpheli bağımlılık ağacında bir yerdedir. Son iyi release'in package.json'unu mevcut olanın yanına yapıştırın. Değişmemiş blokları zihninizde çıkarın ve vurgulanan sürüm aralıklarına odaklanın. Düzeltme genellikle bir kütüphanenin son yeşil build'de sabitlenmiş sürüme downgrade edilmesidir. Şüpheliyi bulduktan sonra, upstream sorun çözülene kadar tam bir sürümle (caret yok, tilde yok) kilitleyin.
Yerel manifestinizi bir takım arkadaşınınkiyle karşılaştırmak
İki mühendis, bir zorlu birleştirme, rebase'in sonunda iki farklı package.json dosyası. Lockfile daha da karışıktır. Hangi anahtarların anlaşamadığını görmek için iki manifesti yan yana yapıştırın, sonra okumadan git merge -X theirs'in sonucunu kabul etmek yerine onları kasıtlı olarak çözün. Bu aynı zamanda, npm install'i sizinkinden farklı bir ağaç alan ve bir manifest sapmasından şüphelendiğiniz yeni bir katkıcıyı işe alırken doğru araçtır.
Bir kütüphanenin package.json'unun publish öncesi incelemesi
Bir kütüphanede npm publish çalıştırmadan önce, önemli olan manifest alanları bir uygulamadan farklıdır: main, module, types, exports, files, peerDependencies, engines. Yayımlanmak üzere olan manifesti son yayımlananla diff edin. Düşürülmüş bir peerDependencies girişi, değişmiş bir exports koşulu veya sıkılmış bir engines aralığı, npm'in kendisinin sizi uyarmayacağı şekillerde tüketicileri kırabilir. Node.js packages docs bu alanların ne anlama geldiğine dair referanstır.
Bilinmeye değer package.json alanları
Gerçek package.json diff'lerinde görünen alanlar ve ne anlama geldikleri. Bir Renovate PR'ını onaylamadan veya manifestin her ikisine de dokunan iki dalı birleştirmeden önce taramaya değer.
| Topic | What this tool does |
|---|
| dependencies vs devDependencies vs peerDependencies | dependencies paketinizle birlikte gönderilir ve onu tüketen herkes tarafından yüklenir. devDependencies yalnızca proje kökünde npm install çalıştırdığınızda yüklenir, asla aşağı akış tüketicileri için değil. peerDependencies, kütüphanenizin host'un sağlamasını beklediği paketlerdir (tipik olarak React, test framework'ü, bundler) ve npm 7+, çakışmadıkça onları otomatik olarak yükleyecektir. Bir paketi bu bloklar arasında taşımak, kurulum maliyetini kimin ödeyeceğini değiştirir. |
|---|
| Caret (^) vs tilde (~) semver aralıkları | Caret ^1.2.3, 2.0.0 dahil olmamak üzere herhangi bir sürüme izin verir; bu npm'in varsayılanı ve en gevşek yaygın aralığıdır. Tilde ~1.2.3 yalnızca yamalara, 1.3.0 dahil olmamak üzere izin verir. 1.2.x tilde ile aynıdır. * herhangi bir sürüm anlamına gelir (üretimde kullanmayın). latest kurulum zamanında çözülür ve yeniden üretilemez build'ler üretir, bu yüzden kaçının. |
|---|
| Tam sabitleme (aralık öneki yok) | Caret veya tilde olmadan "react": "18.2.0" yazmak o tam sürüme sabitler. Bir lockfile ile birleştirildiğinde, bu size güvenlik yamalarını otomatik olarak hiç almama pahasına en yeniden üretilebilir kurulumu verir. Bazı ekipler her şeyi sabitler; diğerleri caret artı lockfile kombinasyonuna dayanır. Evrensel olarak doğru bir cevap yoktur, ama takas daha deterministik build'lere karşı daha güncel olmayan bağımlılıklardır. |
|---|
| package-lock.json determinizmi | package-lock.json, geçişliler dahil bağımlılık ağacındaki her paketin tam çözülmüş sürümünü kaydeder. npm ci lockfile'dan yükler ve onu değiştirmeyi reddeder; npm install, bir aralık daha yeni bir sürüme izin verirse onu güncelleyebilir. CI için her zaman npm ci kullanın. Geliştiriciler için, sonuçtaki lockfile değişikliğini commit ettiğiniz sürece npm install tamamdır. |
|---|
| Monorepo'lar için workspaces alanı | workspaces dizisi, npm'e kardeş dizinleri bir monorepo'da bağlantılı paketler olarak ele almasını söyler. Kökte npm install tüm workspaces'leri yükler ve tek bir hoist edilmiş node_modules ağacı oluşturur. Yarn ve pnpm kendi kurallarıyla workspaces'i destekler ve özellikle pnpm daha az agresif hoist eder, bu da kurulum zamanında daha fazla bağımlılık sızıntısı bug'ı yakalar. |
|---|
| engines alanı | engines.node, paketinizin desteklediği Node.js sürümlerini bildirir. Varsayılan olarak npm yalnızca host bunu ihlal ettiğinde uyarır; .npmrc'deki engine-strict=true bunu sert bir hataya dönüştürür. engines alanını bump etmek, eski Node'a takılı tüketiciler için kırıcı bir değişikliktir ve bir Renovate "chore" PR'ında saklanan türden bir değişikliktir. Her zaman engines diff'ini okuyun. |
|---|
| ES modules için exports alanı | exports alanı, tüketicilerin paketinizden hangi yolları içe aktarabileceğini ve hangi koşulların (import, require, types, node, browser) hangi dosyalara çözüldüğünü kontrol eder. Bir giriş eklemek veya kaldırmak aşağı akış kodu için kırıcı bir değişikliktir. Node.js packages dokümantasyonu çözüm kurallarını ayrıntılı olarak kapsar; bilerek yeni bir giriş noktası eklemediğiniz sürece herhangi bir exports diff'ini major sürüme değer bir düzenleme olarak ele alın. |
|---|
| package.json içinde dosya sıralaması | package.json'daki üst düzey anahtarlar için zorlanmış bir sıra yoktur. Geleneksel olarak çoğu proje name, version, description, sonra scripts, sonra bağımlılıklarla başlar. Bağımlılık blokları içinde anahtara göre alfabetik sıra fiili standarttır ve çoğu paket yöneticisi kaydetmede bloğu sıralar. Yeniden sıralanmış ama aksi halde aynı girişleri gösteren bir diff genellikle bir araç farkıdır, gerçek bir değişiklik değildir. |
|---|
Package.json diff: sıkça sorulan sorular
Bu npm diff'ten veya npm-check-updates'ten nasıl farklı?
npm diff, registry üzerinde bir paketin iki yayımlanmış sürümünü, tarball'ları ve kaynakları dahil karşılaştıran yerleşik bir npm komutudur. npm-check-updates (ncu), manifestinizdeki hangi bağımlılıklar için daha yeni sürümlerin mevcut olduğunu raporlar. Hiçbiri size diskte veya iki dalda sahip olduğunuz iki rastgele package.json dosyası arasındaki farkı göstermez. Bu araç bunu yapar. Yükseltmeniz gerektiğini öğrenmek için ncu'yu, sürümler arasındaki registry tarafı değişiklikleri görmek için npm diff'i ve kendi önce-ve-sonra manifestinizi yan yana görünümde okumak için bu sayfayı kullanın.
Güvenlik denetler mi veya bilinen güvenlik açıklarını kontrol eder mi?
Hayır. Bu sayfa yalnızca metni diff eder. npm registry'sini, GitHub Advisory Database'i veya herhangi bir güvenlik açığı hizmetini sorgulamaz. Güvenlik denetimi için yüklenmiş bir ağaca karşı npm audit çalıştırın, paket kaynağını doğrulamak için npm audit signatures kullanın veya Snyk, Socket veya Dependabot uyarılarına dayanın. Bu araç, manifest'te neyin değiştiğini bilmek istediğinizde doğru çağrıdır. Değişikliğin sevk için güvenli olup olmadığını bilmek istediğinizde yanlış çağrıdır.
Geçişli bağımlılık değişikliklerini algılar mı?
Yalnızca manifestten değil. package.json yalnızca doğrudan bağımlılıkları ve istenen aralıklarını listeler. Geçişliler dahil tam çözülmüş ağaç package-lock.json (veya yarn.lock veya pnpm-lock.yaml) içinde yaşar. Çözülmüş ağaçları karşılaştırmak için her iki lockfile'ı bir diff'e yapıştırın. Lockfile'lar büyük olduğundan, compare-json sayfamız onları bundan daha iyi işler. Özellikle pnpm-lock.yaml için compare-yaml kullanın. Bu sayfa manifest için optimize edilmiştir.
İki package-lock.json dosyasını nasıl karşılaştırırım?
Bir manifest yapacağınız gibi her iki lockfile'ı da bölmelere yapıştırın. Araç onları JSON olarak parse edecek, düzgün biçimlendirecek ve diff edecek. Lockfile'ların binlerce satıra çıkabileceğini unutmayın, bu yüzden vurgulanan diff uzun olabilir. Önce üst düzey packages girişlerine, sonra version alanlarına odaklanın. Yaklaşık beş bin satırdan büyük dosyalar için compare-json sayfamız daha iyi uyar çünkü aynı motorla büyük JSON yüklerini işleyecek şekilde kurulmuştur.
Caret (^) ve tilde (~) aralıkları arasındaki fark nedir?
Her ikisi de manifesti elle düzenlemeden güncellemelere izin veren semver aralıklarıdır. Caret ^1.2.3, en soldaki sıfır olmayan haneyi değiştirmeyen herhangi bir sürüme izin verir, böylece 1.2.3'ten 1.999.999'a kabul edilir, ancak 2.0.0 kabul edilmez. Tilde ~1.2.3 daha katıdır: yalnızca yama güncellemelerine izin verir, böylece 1.2.3'ten 1.2.999'a kabul edilir ancak 1.3.0 kabul edilmez. Caret npm varsayılanıdır ve daha gevşek aralıktır; tilde, bir kütüphanenin minor sürümlerde kırma geçmişi olduğunda uzandığınız şeydir.
Büyük lockfile'lar için boyut sınırları var mı?
Pratik olarak evet. Diff tarayıcınızda çalışır, bu yüzden çok büyük girdiler (örneğin bir monorepo'dan 20.000 satırlık bir lockfile) belleğe bağlı olarak sayfayı yavaşlatabilir veya sekmeyi durdurabilir. Tipik uygulama manifestleri ve taraf başına birkaç bin satıra kadar lockfile'lar için diff fiilen anında tamamlanır. Daha büyük dosyalar için compare-json sayfamız daha iyi giriş noktasıdır. Düzenli olarak büyük lockfile'ları karşılaştırıyorsanız, yerelde git diff package-lock.json çalıştırmayı ve bir pager'a pipe etmeyi düşünün; o iş akışı herhangi bir tarayıcı aracından daha ileri ölçeklenir.
Gizlilik ve bunun nasıl çalıştığı
Manifestleriniz tarayıcınızdan asla ayrılmaz. Diff, JSON ayrıştırma, vurgulama ve render hepsi makinenizde çalışır. Metni yüklemiyoruz, kaydetmiyoruz veya herhangi bir üçüncü taraf hizmetine geçirmiyoruz. Bu özellikle tescilli kod için önemlidir: yayımlanmamış bir kütüphanenin package.json'unu veya özel bir reponun lockfile'ını bir bulut hizmetine yapıştırmak, özellikle manifest dahili scoped paketleri, özel registry hostlarını veya geliştirilmekte olan ürün adlarını adlandırdığında, başlı başına işvereninizin veri işleme politikasını ihlal edebilir. Talebi doğrulamak basittir. Tarayıcınızın DevTools'unu açın, Network sekmesine geçin, her iki manifesti yapıştırın ve izleyin. Karşılaştırdığınızda giden istek yok. Aynı gizlilik modeli compare-json, pnpm-lock.yaml için compare-yaml ve genel kod incelemesi için git-diff-online dahil diğer araçlarımızda da geçerlidir. Altta yatan spesifikasyon için, Yarn'ın yapılandırma referansına ve npm package.json dokümanlarına bakın.