Diff package.json: confronta manifesti npm online
Incolla il package.json vecchio a sinistra, quello nuovo a destra, e vedi esattamente quali dependencies, scripts ed engines sono cambiati. Gira nel tuo browser, niente viene caricato.
Cosa è questo strumento di diff per package.json
Uno strumento gratuito che gira in browser per confrontare due file npm package.json fianco a fianco. Incolla il manifesto vecchio a sinistra, quello nuovo a destra, e le differenze si evidenziano carattere per carattere. Il testo non lascia mai la tua macchina, cosa che conta quando il manifesto appartiene a un repository privato o a un prodotto non rilasciato.
È pensato per il momento in cui arriva una PR di Renovate o Dependabot e devi sapere cosa è cambiato davvero oltre i bump di versione. Qualcuno ha infilato una modifica di script? Il campo engines è passato da Node 18 a Node 20? Una peerDependency è stata stretta? La vista di diff di GitHub risponde in parte, ma incollare due manifesti in una vista pulita a due pannelli è più rapido quando stai scorrendo più PR di seguito o confrontando rami non ancora pushati.
Sotto il cofano, è lo stesso diff JSON-aware che muove la nostra pagina compare-json, con framing e copy tarati per i flussi npm e yarn. Entrambi i manifesti vengono parsati come JSON e formattati prima che parta il diff, così le differenze cosmetiche di spaziatura non inquinano l'evidenziazione. Se ti serve un diff di testo grezzo per un formato di manifesto non-JSON, il nostro strumento compare-text lo copre, e compare-yaml gestisce pnpm-lock.yaml.
Come funziona davvero il diff
Ogni pannello viene parsato come JSON. Se il parsing riesce, il manifesto è riformattato con indentazione consistente di due spazi e l'ordine delle chiavi è preservato come scritto. Se il parsing fallisce (una virgola di troppo, una graffa mancante, un copia-incolla che ha preso pochi caratteri) lo strumento ricade in modalità testo semplice e ti dice quale riga si è rotta. Una volta che entrambi i lati sono JSON valido, il diff gira carattere per carattere, poi un passaggio di pulizia semantica raggruppa i cambiamenti in blocchi leggibili, così un bump di versione da ^18.2.0 a ^19.0.0 si legge come una modifica, non nove modifiche di carattere.
Le inserzioni nel pannello destro vengono in verde; le cancellazioni nel pannello sinistro vengono in rosso. I due pannelli hanno scroll bloccato insieme, così quando trovi un cambio in fondo a devDependencies da un lato, l'altro salta alla stessa chiave. Siccome il diff è a livello di testo dopo la formattazione, vede i cambi strutturali come li legge una persona: una dipendenza rimossa scompare come riga, un range semver cambiato si evidenzia dentro il valore, uno script nuovo si infila nel blocco scripts nella posizione dove l'hai messo.
Cosa lo strumento volutamente non fa: non è un risolutore di dipendenze. Non ti dirà quali pacchetti transitivi tira un bump di range caret, se un peer è soddisfatto, o se la nuova versione introduce un advisory di sicurezza. Per quello, esegui npm install seguito da npm audit in locale, o usa npm con un servizio che capisce i lockfile come Snyk o gli alert Dependabot di GitHub. Questa pagina ti dice cosa dice il testo del manifesto. Il lavoro di risoluzione spetta al tuo gestore di pacchetti.
Come fare il diff di un package.json in tre passi
Due pannelli di testo, un diff. Niente flag CLI, niente passo di installazione, nessun formato patch da leggere.
- 1
Incolla il manifesto vecchio a sinistra
Copia la versione precedente di package.json dal tuo editor, da git show main:package.json, o da un collega. Incolla nel pannello sinistro. Lo strumento lo parserà come JSON e lo formatterà; se il JSON è invalido, l'editor mostrerà l'errore di parsing così puoi sistemare lo snippet prima di fare il diff.
- 2
Incolla il manifesto nuovo a destra
Fai lo stesso con la versione aggiornata. Se stai revisionando una PR di Renovate o Dependabot, la fonte più facile è il file grezzo dal ramo della PR. Entrambi i file vengono formattati con indentazione consistente, così le modifiche cosmetiche di spaziatura non appariranno come cambi falsi nel diff.
- 3
Leggi le differenze evidenziate
Le cancellazioni appaiono come barrato rosso a sinistra; le inserzioni appaiono in verde a destra. Scorri prima i blocchi di dipendenza, poi controlla la sezione scripts per modifiche di comandi, poi i campi engines e peerDependencies. I bump di versione dentro un singolo valore evidenziano i caratteri cambiati, così puoi distinguere un bump di patch da uno major a colpo d'occhio.
Quando un diff di package.json è la scelta giusta
Revisionare una PR di Renovate o Dependabot
Un bot apre quindici PR in una mattinata. La maggior parte è routine, ma una ha infilato un cambio di script, o una peerDependency stretta, o un bump engines che rompe la tua immagine CI. Il titolo della PR dice "chore(deps): bump foo from 4.1.0 to 4.2.1" e ti fidi col pilota automatico. Incolla il package.json prima-e-dopo nel diff e puoi verificare in cinque secondi che niente altro si è mosso. Questa è la singola ragione più comune per cui gli ingegneri JS vanno a prendere un diff di manifesto.
Confrontare due rami prima di mergiare
Tu e un collega avete entrambi toccato package.json su rami feature separati. Git mergiarà pulito perché le modifiche sono in blocchi diversi, ma un merge pulito non significa uno corretto. Incolla i manifesti dei due rami nel diff per individuare uno script che un ramo ha lasciato cadere, una dipendenza che un ramo ha downgradato, o un conflitto dove entrambi i rami hanno aggiunto lo stesso pacchetto in versioni diverse. Più economico che scoprirlo dopo che CI esegue npm ci sul risultato mergato.
Auditare cosa npm install ha promosso in package-lock.json
Modificare package.json è metà del cambio. L'altra metà è cosa package-lock.json registra sull'albero risolto. Dopo aver eseguito npm install, incolla il vecchio lockfile accanto al nuovo per vedere quali pacchetti transitivi sono venuti in giro. Aggiunte sorprendenti sono comuni quando un range caret ha tirato un nuovo minor di una dipendenza profondamente annidata. Per ispezione grezza di lockfile la nostra pagina compare-json gestisce meglio i file più grandi; questa pagina è la migliore per il manifesto stesso.
Verificare un downgrade dopo una regressione
Esce una release, salta fuori un bug, fai il bisect, e il sospetto è da qualche parte nell'albero di dipendenze. Incolla il package.json dell'ultima release buona accanto a quello attuale. Scarta mentalmente i blocchi non cambiati e concentrati sui range di versione evidenziati. La fix è spesso un downgrade di una libreria alla versione fissata nell'ultimo build verde. Una volta trovato il sospetto, bloccalo con una versione esatta (niente caret, niente tilde) finché il problema upstream non è risolto.
Confrontare il tuo manifesto locale con quello di un collega
Due ingegneri, un merge spinoso, due file package.json diversi alla fine del rebase. Il lockfile è ancora più confuso. Incolla i due manifesti fianco a fianco per vedere quali chiavi sono in disaccordo, poi risolvile deliberatamente invece di accettare il risultato di git merge -X theirs senza leggere. Questo è anche lo strumento giusto quando integri un nuovo collaboratore il cui npm install tira un albero diverso dal tuo e sospetti un drift di manifesto.
Revisione pre-publish del package.json di una libreria
Prima di eseguire npm publish su una libreria, i campi del manifesto che contano sono diversi da un'app: main, module, types, exports, files, peerDependencies, engines. Fai il diff del manifesto in procinto di essere pubblicato contro l'ultimo pubblicato. Una voce peerDependencies caduta, una condizione exports cambiata, o un range engines stretto possono rompere i consumatori in modi che npm stesso non ti avviserà. La documentazione dei packages Node.js è il riferimento per cosa significano quei campi.
Campi di package.json che vale la pena conoscere
I campi che spuntano in diff reali di package.json e cosa significano. Vale la pena scorrerli prima di approvare una PR Renovate o mergiare due rami che hanno entrambi toccato il manifesto.
| Topic | What this tool does |
|---|
| dependencies vs devDependencies vs peerDependencies | dependencies vengono spedite col tuo pacchetto e installate da chiunque lo consumi. devDependencies sono installate solo quando esegui npm install nella radice del progetto, mai per consumatori a valle. peerDependencies sono pacchetti che la tua libreria si aspetta che l'host fornisca (tipicamente React, il framework di test, il bundler) e npm 7+ li installerà automaticamente a meno che non confliggano. Spostare un pacchetto tra questi blocchi cambia chi paga il costo di installazione. |
|---|
| Range semver caret (^) vs tilde (~) | Caret ^1.2.3 permette qualunque versione fino a ma non includendo 2.0.0; questo è il default npm e il range comune più largo. Tilde ~1.2.3 permette solo patch, fino a ma non includendo 1.3.0. 1.2.x è uguale alla tilde. * significa qualsiasi versione (non usarlo in produzione). latest risolve al momento dell'installazione e produce build non riproducibili, quindi evitalo. |
|---|
| Pinning esatto (nessun prefisso di range) | Scrivere "react": "18.2.0" senza caret o tilde fissa a quella versione esatta. Combinato con un lockfile, questo ti dà l'installazione più riproducibile al costo di non ricevere mai patch di sicurezza automaticamente. Alcuni team fissano tutto; altri si appoggiano alla combinazione caret più lockfile. Non c'è una risposta universalmente corretta, ma il trade-off è build più deterministici contro dipendenze più obsolete. |
|---|
| Determinismo di package-lock.json | package-lock.json registra la versione risolta esatta di ogni pacchetto nell'albero di dipendenze, transitive incluse. npm ci installa dal lockfile e si rifiuta di modificarlo; npm install potrebbe aggiornarlo se un range permette una versione più recente. Per CI, usa sempre npm ci. Per gli sviluppatori, npm install va bene finché commetti la modifica risultante del lockfile. |
|---|
| Campo workspaces per monorepo | L'array workspaces dice a npm di trattare le directory sorelle come pacchetti collegati in un monorepo. npm install alla radice installa tutti i workspaces e crea un singolo albero node_modules hoisted. Yarn e pnpm supportano i workspaces con le proprie convenzioni, e pnpm in particolare hoista meno aggressivamente, il che becca più bug di leak di dipendenze al momento dell'installazione. |
|---|
| Campo engines | engines.node dichiara le versioni di Node.js che il tuo pacchetto supporta. Di default npm avvisa solo quando l'host viola questo; engine-strict=true in .npmrc lo trasforma in errore duro. Bumpare il campo engines è un cambio rompente per consumatori bloccati su Node vecchio, ed è il tipo di cambio che si nasconde dentro una PR "chore" di Renovate. Leggi sempre il diff engines. |
|---|
| Campo exports per ES modules | Il campo exports controlla quali path i consumatori possono importare dal tuo pacchetto e quali condizioni (import, require, types, node, browser) si risolvono in quali file. Aggiungere o rimuovere una voce è un cambio rompente per il codice a valle. La documentazione dei packages Node.js copre le regole di risoluzione in dettaglio; tratta qualunque diff di exports come una modifica degna di una versione major a meno che non stai aggiungendo deliberatamente un nuovo entry point. |
|---|
| Ordine dei file dentro package.json | Non c'è ordine forzato per le chiavi di livello superiore in package.json. Per convenzione, la maggior parte dei progetti inizia con name, version, description, poi scripts, poi le dipendenze. Dentro i blocchi di dipendenze, l'ordine alfabetico per chiave è lo standard de facto e la maggior parte dei gestori di pacchetti ordineranno il blocco al salvataggio. Un diff che mostra voci riordinate ma per il resto identiche è di solito una differenza di tooling, non un cambio reale. |
|---|
Diff package.json: domande frequenti
In cosa si differenzia da npm diff o npm-check-updates?
npm diff è un comando npm integrato che confronta due versioni pubblicate di un pacchetto sul registry, inclusi i loro tarball e sorgenti. npm-check-updates (ncu) riporta quali dipendenze nel tuo manifesto hanno versioni più recenti disponibili. Nessuno dei due ti mostra la differenza tra due file package.json arbitrari che hai su disco o in due rami. Questo strumento lo fa. Usa ncu per scoprire cosa dovresti aggiornare, npm diff per vedere cambi lato registry tra release, e questa pagina per leggere il tuo manifesto prima-e-dopo in una vista fianco a fianco.
Audita la sicurezza o controlla vulnerabilità note?
No. Questa pagina fa solo il diff del testo. Non interroga il registry npm, il GitHub Advisory Database, o nessun servizio di vulnerabilità. Per audit di sicurezza, esegui npm audit contro un albero installato, usa npm audit signatures per verificare la provenienza del pacchetto, o appoggiati ad alert Snyk, Socket o Dependabot. Questo strumento è la scelta giusta quando vuoi sapere cosa è cambiato nel manifesto. È la scelta sbagliata quando vuoi sapere se il cambio è sicuro da rilasciare.
Rileva cambi di dipendenze transitive?
Non dal manifesto da solo. package.json elenca solo dipendenze dirette e i loro range richiesti. L'albero risolto completo, transitive incluse, vive in package-lock.json (o yarn.lock o pnpm-lock.yaml). Per confrontare alberi risolti, incolla entrambi i lockfile in un diff. Siccome i lockfile sono grandi, la nostra pagina compare-json li gestisce meglio di questa. Per pnpm-lock.yaml in particolare, usa compare-yaml. Questa pagina è ottimizzata per il manifesto.
Come confronto due file package-lock.json?
Incolla entrambi i lockfile nei pannelli come faresti con un manifesto. Lo strumento li parserà come JSON, formatterà e farà il diff. Sappi che i lockfile possono arrivare a migliaia di righe, quindi il diff evidenziato può essere lungo. Concentrati prima sulle voci packages di livello superiore, poi sui campi version. Per file più grandi di circa cinquemila righe, la nostra pagina compare-json calza meglio perché è impostata per gestire payload grandi di JSON con lo stesso motore.
Qual è la differenza tra i range caret (^) e tilde (~)?
Entrambi sono range semver che permettono aggiornamenti senza modificare manualmente il manifesto. Il caret ^1.2.3 permette qualunque versione che non cambia la cifra non-zero più a sinistra, quindi 1.2.3 fino a 1.999.999 sono accettate, ma 2.0.0 no. La tilde ~1.2.3 è più stretta: permette solo aggiornamenti patch, quindi 1.2.3 fino a 1.2.999 sono accettate ma 1.3.0 no. Caret è il default npm e il range più largo; tilde è quello che prendi quando una libreria ha una storia di rotture in release minor.
Ci sono limiti di dimensione per lockfile grandi?
In pratica sì. Il diff gira nel tuo browser, quindi input molto grandi (un lockfile di 20.000 righe da un monorepo, per esempio) possono rallentare la pagina o bloccare la tab a seconda della memoria. Per manifesti tipici di app e lockfile fino a qualche migliaio di righe per lato, il diff completa praticamente all'istante. Per file più grandi, la nostra pagina compare-json è il punto d'ingresso migliore. Se confronti regolarmente lockfile enormi, considera di eseguire git diff package-lock.json in locale e pipare a un pager; quel flusso scala più in là di qualunque strumento browser.
Privacy e come funziona
I tuoi manifesti non lasciano mai il tuo browser. Il diff, il parsing JSON, l'evidenziazione e il rendering girano tutti sulla tua macchina. Non carichiamo il testo, non lo logghiamo, e non lo passiamo a nessun servizio di terze parti. Questo conta specificamente per codice proprietario: incollare il package.json di una libreria non rilasciata o il lockfile di un repo privato in un servizio cloud può di per sé violare la policy di gestione dati del tuo datore di lavoro, specialmente quando il manifesto nomina pacchetti scoped interni, host di registry privati, o nomi di prodotti in sviluppo. Verificare l'affermazione è diretto. Apri i DevTools del browser, passa alla tab Network, incolla entrambi i manifesti, e guarda. Non ci sono richieste in uscita quando confronti. Lo stesso modello di privacy regge nei nostri altri strumenti, inclusi compare-json, compare-yaml per pnpm-lock.yaml, e git-diff-online per revisione di codice generale. Per la specifica sottostante, vedi il riferimento di configurazione di Yarn e i docs di package.json di npm.