Il campo exports in package.json: a che cosa serve
exports dice da quale file parte un pacchetto Node importato per nome. Se il campo c'è, prevale su main. I sottopercorsi non dichiarati non si importano.
In questa guida (3)
Chi pubblica un pacchetto Node deve dire da quale file parte, quando un altro progetto lo importa per nome. Il campo exports di package.json è il modo previsto dalle versioni di Node ancora supportate. main resta il campo storico, e cede il passo se exports c'è. Ho letto la pagina Packages della documentazione Node.js v26.13.0 il 2 novembre 2026. Non ho lanciato node.
A che cosa serve main
La documentazione data main alla versione 0.4.0. È una stringa, un percorso. Definisce il punto di ingresso del pacchetto importato per nome, con una ricerca in node_modules. Definisce anche lo script usato quando la cartella del pacchetto viene caricata con require(). L'esempio della pagina è "main": "./index.js", e require('./path/to/directory') risolve ./path/to/directory/index.js.
La stessa voce aggiunge la precedenza: se exports esiste, prevale su main quando si importa il pacchetto per nome.
A che cosa serve exports
exports è stato introdotto nella 12.7.0, e la storia della pagina lo chiama un'alternativa più capace del campo main. Può essere un oggetto, una stringa o un array di stringhe. Definisce i punti di ingresso quando il pacchetto è importato per nome, da node_modules o con un riferimento al proprio nome. I percorsi devono essere URL di file relativi che iniziano con ./.
Con l'oggetto si nominano i sottopercorsi. Il punto "." è l'ingresso principale. Una chiave come "./submodule.js" pubblica un file interno sotto un nome scelto dall'autore. Le condizioni, nella stessa documentazione, servono a dare percorsi diversi a seconda dell'ambiente, compreso il caso in cui il pacchetto arrivi da require o da import.
Che cosa succede a un sottopercorso non dichiarato
Quando exports è definito, i sottopercorsi del pacchetto sono incapsulati e non sono più disponibili a chi importa. require('pkg/subpath.js') lancia ERR_PACKAGE_PATH_NOT_EXPORTED se quel sottopercorso non è nella mappa. La pagina precisa che non è un incapsulamento forte: un require con il percorso assoluto del file, dentro node_modules, lo carica ancora.
Per i progetti che devono ancora parlare con Node 10 o precedenti, la documentazione chiede di tenere main. Se si aggiunge exports a un pacchetto già pubblicato, gli ingressi che prima funzionavano e che non vengono riesportati smettono di essere importabili. La pagina lo tratta come un cambiamento incompatibile, e consiglia di riesportare ogni ingresso che i consumatori usavano già.
Il comando che installa dal lockfile è un'altra decisione, sulla pagina npm ci e npm install.
Fonte: Node.js v26.13.0, Modules: Packages.
Foto di copertina: Henry Söderlund, Cardboard boxes, Wikimedia Commons, CC BY 2.0. La descrizione del file è una pila di cartone.


