Package.json-diff: sammenlign npm-manifester på nettet
Lim inn det gamle package.json til venstre, det nye til høyre, og se nøyaktig hvilke dependencies, scripts og engines som har endret seg. Kjører i nettleseren, ingenting lastes opp.
Hva dette package.json-diff-verktøyet er
Et gratis verktøy som kjører i nettleseren for å sammenligne to npm package.json-filer side ved side. Lim inn det gamle manifestet til venstre, det nye til høyre, og forskjellene markeres tegn for tegn. Teksten forlater aldri maskinen din, noe som betyr noe når manifestet hører til et privat repo eller et uutgitt produkt.
Det er bygget for det øyeblikket en Renovate- eller Dependabot-PR lander og du må vite hva som faktisk endret seg utover versjons-bumpene. Smuglet noen inn en script-redigering? Flyttet engines-feltet seg fra Node 18 til Node 20? Ble en peerDependency strammet? GitHubs diff-visning besvarer en del av dette, men å lime inn to manifester i en ren tovinduvisning er raskere når du går gjennom flere PR-er på rad eller sammenligner grener som ikke er pushet ennå.
Under panseret er dette samme JSON-bevisste diff som driver vår compare-json-side, med ramme og tekst stemt mot npm- og yarn-flyter. Begge manifester parses som JSON og pretty-printes før diffen kjører, så kosmetiske mellomromsforskjeller forurenser ikke markeringen. Hvis du trenger rå tekst-diff for et ikke-JSON-manifestformat, dekker vårt compare-text-verktøy det, og compare-yaml håndterer pnpm-lock.yaml.
Hvordan diffen faktisk fungerer
Hvert vindu parses som JSON. Hvis parsingen lykkes, omformateres manifestet med konsekvent to-mellomroms-innrykk og nøkkelrekkefølgen bevares som skrevet. Hvis parsingen feiler (et villfarent komma, en manglende klamme, en kopi-lim som tok for få tegn) faller verktøyet tilbake til klartekstmodus og forteller deg hvilken linje som brakk. Når begge sider er gyldig JSON, kjører diffen tegn for tegn, deretter grupperer en semantisk oppryddingsfase endringene tilbake til lesbare biter, så et versjonsbump fra ^18.2.0 til ^19.0.0 leses som én redigering, ikke ni tegnredigeringer.
Innsettinger i høyre vindu rendres i grønt; slettinger i venstre vindu rendres i rødt. De to vinduene er scroll-låst sammen, så når du finner en endring dypt inne i devDependencies på den ene siden, hopper den andre til samme nøkkel. Fordi diffen er på tekstnivå etter pretty-print, ser den strukturelle endringer slik et menneske leser dem: en fjernet avhengighet forsvinner som en linje, et endret semver-intervall markeres inne i verdien, et nytt script glir inn i scripts-blokken på posisjonen du satte det.
Hva verktøyet bevisst ikke gjør: det er ikke en avhengighetsløser. Det vil ikke fortelle deg hvilke transitive pakker et caret-intervall-bump trekker inn, om en peer er oppfylt, eller om den nye versjonen introduserer en sikkerhetsadvarsel. Til det, kjør npm install etterfulgt av npm audit lokalt, eller bruk npm med en lockfile-bevisst tjeneste som Snyk eller GitHubs Dependabot-varsler. Denne siden forteller deg hva manifestteksten sier. Oppløsningsarbeidet hører til pakkebehandleren din.
Hvordan diffe en package.json i tre trinn
To tekstvinduer, én diff. Ingen CLI-flagg, ingen installasjonstrinn, intet patch-format å lese.
- 1
Lim inn det gamle manifestet til venstre
Kopier den forrige versjonen av package.json fra editoren din, fra git show main:package.json, eller fra en lagkamerat. Lim inn i venstre vindu. Verktøyet parser det som JSON og pretty-printer; hvis JSON-en er ugyldig, vil editoren vise parse-feilen så du kan fikse utdraget før diffen.
- 2
Lim inn det nye manifestet til høyre
Gjør det samme med den oppdaterte versjonen. Hvis du går gjennom en Renovate- eller Dependabot-PR, er den enkleste kilden råfilen fra PR-grenen. Begge filer pretty-printes med konsekvent innrykk, så kosmetiske mellomroms-redigeringer dukker ikke opp som falske endringer i diffen.
- 3
Les de markerte forskjellene
Slettinger vises som røde overstrekninger til venstre; innsettinger vises som grønne til høyre. Skann avhengighetsblokkene først, sjekk så scripts-seksjonen for kommando-redigeringer, deretter engines- og peerDependencies-feltene. Versjonsbumps innenfor en enkelt verdi markerer de endrede tegnene, så du kan skille et patch-bump fra et major med ett blikk.
Når en package.json-diff er det riktige valget
Gå gjennom en Renovate- eller Dependabot-PR
En bot åpner femten PR-er på en formiddag. De fleste er rutine, men én smuglet inn en script-endring, eller en strammet peerDependency, eller et engines-bump som bryter CI-imaget ditt. PR-tittelen sier "chore(deps): bump foo from 4.1.0 to 4.2.1" og du stoler på autopilot. Lim inn før-og-etter-package.json i diffen og du kan verifisere på fem sekunder at ingenting annet rørte seg. Dette er den enkeltvis vanligste grunnen til at JS-ingeniører strekker seg etter en manifest-diff.
Sammenligne to grener før merge
Du og en kollega rørte begge ved package.json på separate feature-grener. Git merger rent fordi redigeringene er i forskjellige blokker, men en ren merge betyr ikke en korrekt. Lim inn de to grenenes manifester i diffen for å fange et script som én gren slapp, en avhengighet som én gren nedgraderte, eller en kollisjon hvor begge grenene la til den samme pakken i forskjellige versjoner. Billigere enn å oppdage det etter at CI har kjørt npm ci mot det mergede resultatet.
Revidere hva npm install forfremmet i package-lock.json
Å redigere package.json er halvparten av endringen. Den andre halvparten er hva package-lock.json registrerer om det oppløste treet. Etter å ha kjørt npm install, lim inn den gamle lockfilen ved siden av den nye for å se hvilke transitive pakker som ble med på turen. Overraskelsestillegg er vanlige når et caret-intervall trakk inn en ny minor av en dypt nestet avhengighet. Til rå lockfile-inspeksjon håndterer vår compare-json-side de større filene bedre; denne siden er best for selve manifestet.
Sjekke en nedgradering etter en regresjon
En utgivelse går ut, en bug dukker opp, du bisecter, og den mistenkte er et eller annet sted i avhengighetstreet. Lim inn package.json fra den siste gode utgivelsen ved siden av den nåværende. Stryk uendrede blokker mentalt og fokuser på de markerte versjonsintervallene. Fiksen er ofte en nedgradering av ett bibliotek til versjonen som var pinned i den siste grønne builden. Når du har funnet den mistenkte, lås den med en eksakt versjon (ingen caret, ingen tilde) til oppstrømsproblemet er løst.
Sammenligne ditt lokale manifest med en lagkamerats
To ingeniører, én vrien merge, to forskjellige package.json-filer ved slutten av rebasen. Lockfilen er enda mer forvirret. Lim inn begge manifester side ved side for å se hvilke nøkler som er uenige, løs dem så bevisst i stedet for å akseptere resultatet av git merge -X theirs uten å lese. Dette er også det riktige verktøyet når du onboarder en ny bidragsyter hvis npm install samler et annet tre enn ditt og du mistenker en manifest-drift.
Pre-publish-gjennomgang av et biblioteks package.json
Før du kjører npm publish på et bibliotek, er manifestfeltene som betyr noe annerledes enn for en app: main, module, types, exports, files, peerDependencies, engines. Diff manifestet som er i ferd med å bli publisert mot det sist publiserte. En sluppet peerDependencies-oppføring, en endret exports-betingelse, eller et strammet engines-intervall kan bryte forbrukere på måter som npm selv ikke advarer deg om. Node.js packages docs er referansen for hva de feltene betyr.
Package.json-felter verdt å kjenne
Feltene som dukker opp i ekte package.json-differ og hva de betyr. Verdt å skanne før du godkjenner en Renovate-PR eller merger to grener som begge rørte ved manifestet.
| Topic | What this tool does |
|---|
| dependencies vs devDependencies vs peerDependencies | dependencies følger med pakken din og installeres av enhver som forbruker den. devDependencies installeres bare når du kjører npm install i prosjektroten, aldri for nedstrømsforbrukere. peerDependencies er pakker som biblioteket ditt forventer at verten leverer (typisk React, testrammeverket, bundleren) og npm 7+ vil installere dem automatisk med mindre de er i konflikt. Å flytte en pakke mellom disse blokkene endrer hvem som betaler installasjonskostnaden. |
|---|
| Caret- (^) vs tilde- (~) semver-intervaller | Caret ^1.2.3 tillater enhver versjon opp til men ikke inkludert 2.0.0; dette er npms standard og det løseste vanlige intervallet. Tilde ~1.2.3 tillater bare patches, opp til men ikke inkludert 1.3.0. 1.2.x er det samme som tilde. * betyr enhver versjon (ikke bruk dette i produksjon). latest oppløses ved installasjonstid og produserer ikke-reproduserbare builds, så unngå det. |
|---|
| Eksakt pinning (intet intervallprefiks) | Å skrive "react": "18.2.0" uten caret eller tilde pinner til den eksakte versjonen. Kombinert med en lockfile gir dette deg den mest reproduserbare installasjonen til prisen av aldri å motta sikkerhetspatches automatisk. Noen team pinner alt; andre stoler på caret-pluss-lockfile-kombinasjonen. Det er ikke noe universelt riktig svar, men avveiningen er mer deterministiske builds mot mer utdaterte avhengigheter. |
|---|
| package-lock.json-determinisme | package-lock.json registrerer den eksakt oppløste versjonen av hver pakke i avhengighetstreet, inkludert transitive. npm ci installerer fra lockfilen og nekter å modifisere den; npm install kan oppdatere den hvis et intervall tillater en nyere versjon. Til CI, bruk alltid npm ci. Til utviklere er npm install ok så lenge du commiter den resulterende lockfile-endringen. |
|---|
| workspaces-felt for monorepoer | workspaces-arrayet sier til npm at det skal behandle søsterkataloger som lenkede pakker i et monorepo. npm install i roten installerer alle workspaces og oppretter et enkelt hoistet node_modules-tre. Yarn og pnpm støtter workspaces med sine egne konvensjoner, og pnpm spesielt hoister mindre aggressivt, noe som fanger flere avhengighets-lekkasje-bugs ved installasjonstid. |
|---|
| engines-felt | engines.node erklærer Node.js-versjonene pakken din støtter. Som standard advarer npm bare når verten bryter dette; engine-strict=true i .npmrc gjør det til en hard feil. Å bumpe engines-feltet er en brytende endring for forbrukere som sitter fast på eldre Node, og det er den slags endring som gjemmer seg inne i en Renovate-"chore"-PR. Les alltid engines-diffen. |
|---|
| exports-felt for ES modules | exports-feltet styrer hvilke stier forbrukere kan importere fra pakken din og hvilke betingelser (import, require, types, node, browser) som oppløses til hvilke filer. Å legge til eller fjerne en oppføring er en brytende endring for nedstrømskode. Node.js packages-dokumentasjonen dekker oppløsningsreglene i detalj; behandle enhver exports-diff som en major-versjons-verdig redigering med mindre du bevisst legger til et nytt inngangspunkt. |
|---|
| Filrekkefølge inne i package.json | Det er ingen påtvunget rekkefølge for topp-nivå-nøkler i package.json. Etter konvensjon starter de fleste prosjekter med name, version, description, så scripts, så avhengigheter. Innenfor avhengighetsblokker er alfabetisk rekkefølge per nøkkel de facto-standarden og de fleste pakkebehandlere sorterer blokken ved lagring. En diff som viser omorganiserte men ellers identiske oppføringer, er som regel en verktøysforskjell, ikke en reell endring. |
|---|
Package.json-diff: ofte stilte spørsmål
Hvordan skiller dette seg fra npm diff eller npm-check-updates?
npm diff er en innebygd npm-kommando som sammenligner to publiserte versjoner av en pakke på registry, inkludert tarballs og kilder. npm-check-updates (ncu) rapporterer hvilke avhengigheter i manifestet ditt som har nyere versjoner tilgjengelig. Ingen av dem viser deg forskjellen mellom to vilkårlige package.json-filer du har på disk eller i to grener. Dette verktøyet gjør det. Bruk ncu for å finne ut at du burde oppgradere, npm diff for å se registry-side-endringer mellom utgivelser, og denne siden for å lese ditt eget før-og-etter-manifest i en side-ved-side-visning.
Reviderer det sikkerhet eller sjekker for kjente sårbarheter?
Nei. Denne siden differ bare teksten. Den spør ikke npm-registry, GitHub Advisory Database, eller noen sårbarhetstjeneste. Til sikkerhetsrevisjon, kjør npm audit mot et installert tre, bruk npm audit signatures for å verifisere pakkeopprinnelse, eller len deg på Snyk-, Socket- eller Dependabot-varsler. Dette verktøyet er det riktige valget når du vil vite hva som har endret seg i manifestet. Det er det feile valget når du vil vite om endringen er trygg å sende.
Oppdager det transitive avhengighetsendringer?
Ikke fra manifestet alene. package.json lister bare direkte avhengigheter og deres forespurte intervaller. Det fulle oppløste treet, inkludert transitive, lever i package-lock.json (eller yarn.lock eller pnpm-lock.yaml). For å sammenligne oppløste trær, lim inn begge lockfiler i en diff. Fordi lockfiler er store, håndterer vår compare-json-side dem bedre enn denne. For pnpm-lock.yaml spesifikt, bruk compare-yaml. Denne siden er optimalisert for manifestet.
Hvordan sammenligner jeg to package-lock.json-filer?
Lim inn begge lockfilene i vinduene på samme måte som du ville et manifest. Verktøyet parser dem som JSON, pretty-printer og differ. Vær oppmerksom på at lockfiler kan komme opp i tusenvis av linjer, så den markerte diffen kan være lang. Fokuser på topp-nivå-packages-oppføringer først, så på version-feltene. For filer større enn omtrent fem tusen linjer passer vår compare-json-side bedre fordi den er satt opp til å håndtere store JSON-payloads med samme motor.
Hva er forskjellen mellom caret- (^) og tilde- (~) intervaller?
Begge er semver-intervaller som tillater oppdateringer uten å manuelt redigere manifestet. Caret ^1.2.3 tillater enhver versjon som ikke endrer det venstreste ikke-null-sifferet, så 1.2.3 til 1.999.999 aksepteres, men 2.0.0 ikke. Tilde ~1.2.3 er strengere: tillater bare patch-oppdateringer, så 1.2.3 til 1.2.999 aksepteres men 1.3.0 ikke. Caret er npms standard og det løsere intervallet; tilde er hva du strekker deg etter når et bibliotek har en historie med å bryte i minor-utgivelser.
Er det størrelsesgrenser for store lockfiler?
Praktisk sett ja. Diffen kjører i nettleseren din, så veldig store input (en 20 000-linjers lockfile fra et monorepo, for eksempel) kan sakke ned siden eller stoppe fanen avhengig av minne. For typiske app-manifester og lockfiler opptil noen tusen linjer per side fullføres diffen praktisk talt umiddelbart. For større filer er vår compare-json-side det bedre inngangspunktet. Hvis du regelmessig sammenligner enorme lockfiler, vurder å kjøre git diff package-lock.json lokalt og pipe til en pager; den flyten skalerer lenger enn noe nettleserverktøy.
Personvern og hvordan dette fungerer
Manifestene dine forlater aldri nettleseren din. Diffen, JSON-parsingen, markeringen og renderingen kjører alle på maskinen din. Vi laster ikke opp teksten, logger den ikke, eller sender den til noen tredjepartstjeneste. Dette betyr noe spesifikt for proprietær kode: å lime inn package.json fra et uutgitt bibliotek eller lockfilen fra et privat repo i en skytjeneste kan i seg selv bryte arbeidsgiverens databehandlingspolicy, spesielt når manifestet navngir interne scoped-pakker, private registry-verter, eller produktnavn under utvikling. Å verifisere påstanden er rett frem. Åpne nettleserens DevTools, bytt til Network-fanen, lim inn begge manifester og se. Det er ingen utgående forespørsler når du sammenligner. Samme personvernmodell holder på tvers av våre andre verktøy, inkludert compare-json, compare-yaml for pnpm-lock.yaml, og git-diff-online for generell kodegjennomgang. For den underliggende spesifikasjonen, se Yarns konfigurasjonsreferanse og npm package.json-dokumentasjonen.