Pubblicare su npm e versionamento semantico

Prima della pubblicazione, esegua sempre npm publish --dry-run. Questa operazione simula la pubblicazione senza caricare effettivamente nulla e mostra esattamente quali file verrebbero inclusi, le relative dimensioni e il contenuto dell'archivio tar del pacchetto. Consente di individuare errori comuni, come l'inclusione accidentale dei file sorgente o l'assenza della directory dist.

Controlli ciò che viene pubblicato utilizzando il campo files in package.json: "files": ["dist", "README.md"]. Questo approccio basato su un elenco di file consentiti è più sicuro di .npmignore, che utilizza un elenco di file esclusi e può esporre file sensibili se ci si dimentica di aggiungerli. Includa sempre dist, le dichiarazioni di tipo e la documentazione. Non includa mai src, i test o node_modules.

I pacchetti npm seguono il versionamento semantico (semver): MAJOR.MINOR.PATCH. Incrementi MAJOR per le modifiche incompatibili, come la rimozione di props o la modifica delle firme dell'API. Incrementi MINOR per le nuove funzionalità compatibili con le versioni precedenti, come nuovi componenti o nuove props opzionali. Incrementi PATCH per le correzioni di bug compatibili con le versioni precedenti. La versione 0.x.x è considerata pre-stabile: qualsiasi elemento potrebbe subire modifiche incompatibili.

Gli identificatori di versione preliminare indicano che una versione non è pronta per la produzione: 1.0.0-alpha.1 per le prime build sperimentali, 1.0.0-beta.2 per le versioni complete nelle funzionalità ma potenzialmente contenenti bug e 1.0.0-rc.1 (release candidate) per le versioni pronte per il test finale. Pubblichi le versioni preliminari con npm publish --tag beta, in modo che non diventino la versione installata per impostazione predefinita.

Changesets è lo strumento standard per gestire il versionamento dei pacchetti e i changelog nelle librerie di componenti. Il flusso di lavoro è il seguente: i collaboratori eseguono yarn changeset add per registrare le modifiche e il relativo tipo (major/minor/patch). La CI esegue yarn changeset version per aggiornare le versioni dei pacchetti. La pubblicazione esegue yarn changeset publish per pubblicare su npm.

Changesets genera e mantiene automaticamente CHANGELOG.md in base ai file changeset sottoposti dai collaboratori. Ogni voce include il numero di versione, la data di rilascio e la descrizione delle modifiche. In questo modo si crea una cronologia leggibile di ogni versione senza dover gestire manualmente il changelog.

semantic-release è uno strumento di versionamento completamente automatizzato che determina la versione successiva a partire dai messaggi di commit convenzionali (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Aggiorna la versione, genera il changelog e pubblica su npm: tutto viene attivato dalla CI in seguito al merge su main. Non è necessaria alcuna gestione manuale delle versioni.

I pacchetti senza scope (my-component) sono sempre pubblici. I pacchetti con scope (@myorg/my-component) sono limitati (privati) per impostazione predefinita: li renda pubblici con npm publish --access public. Per i pacchetti limitati è necessario un account npm a pagamento o un'organizzazione. Verifichi le impostazioni di accesso prima della prima pubblicazione.

La provenienza npm collega il pacchetto pubblicato al commit Git specifico da cui proviene, in modo verificabile. La abiliti con npm publish --provenance in GitHub Actions. Gli utenti possono verificare che il pacchetto installato sia stato compilato esattamente a partire dal commit sorgente mostrato nella pagina del pacchetto sul registro npm. Questo migliora significativamente la sicurezza della catena di approvvigionamento.

Quando una versione presenta un bug critico o una modifica incompatibile, la deprechi: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm mostra un avviso di deprecazione a chiunque installi quella versione. La versione non viene rimossa, perché npm non elimina per impostazione predefinita le versioni già pubblicate, ma gli utenti vengono avvisati di eseguire l'aggiornamento.

I pacchetti con scope utilizzano il formato @scope/package-name. Lo scope è in genere il nome utente npm o il nome dell'organizzazione. I pacchetti con scope rendono chiaro chi mantiene il pacchetto e prevengono conflitti di nomi con i pacchetti senza scope. Utilizzi pacchetti con scope per i pacchetti privati e per quelli open source associati alla propria organizzazione.

Utilizzi npm publish --dry-run per visualizzare in anteprima la pubblicazione e il campo files per controllare ciò che viene pubblicato. Versionamento semantico: MAJOR per le modifiche incompatibili, MINOR per le nuove funzionalità, PATCH per le correzioni. Le versioni preliminari utilizzano i tag -alpha/-beta/-rc. Changesets automatizza il versionamento e la generazione del CHANGELOG per le librerie sviluppate in collaborazione. semantic-release automatizza il processo a partire dai commit convenzionali. Abiliti --provenance per la sicurezza della catena di approvvigionamento. Deprechi le versioni con bug utilizzando npm deprecate.