module.exports ed exports in Node.js, con esempi

module.exports è il valore che un file Node.js dà a qualsiasi altro file che lo carica con require(). All'inizio è un oggetto vuoto: aggiungigli proprietà per esportare più cose, oppure assegnagli un nuovo valore (una funzione, una classe) per esportarne una sola. exports è una variabile scorciatoia che punta allo stesso oggetto, quindi exports.add = ... funziona, ma exports = ... rompe il collegamento e non esporta niente.

const fs = require('fs');

// setup: write a second module next to index.js
fs.writeFileSync('math.js', `
module.exports.add = (a, b) => a + b;
exports.multiply = (a, b) => a * b;
module.exports.PI = 3.14159;
`);

const math = require('./math');

console.log(math.add(2, 3), math.multiply(4, 5), math.PI);
console.log(Object.keys(math));

Ha stampato 5 20 3.14159, poi [ 'add', 'multiply', 'PI' ]. Tutte e tre le righe di math.js hanno aggiunto proprietà allo stesso oggetto, sia passando da module.exports sia da exports, e require('./math') ha restituito quell'oggetto.

Esportare una funzione, una classe o un oggetto

Quando un modulo ha una sola cosa principale, assegnala direttamente a module.exports. Il chiamante riceve così la funzione stessa, non un oggetto che la contiene:

const fs = require('fs');

// setup: two modules, one exports a function, one a class
fs.writeFileSync('greet.js', `
module.exports = function greet(name) {
    return 'Hello, ' + name;
};
`);
fs.writeFileSync('user.js', `
class User {
    constructor(name) { this.name = name; }
    describe() { return this.name + ' (user)'; }
}
module.exports = User;
`);

const greet = require('./greet');
const User = require('./user');

console.log(greet('Ada'));
console.log(new User('Grace').describe());

Ha stampato Hello, Ada e Grace (user). Se vedi TypeError: greet is not a function, il chiamante ha usato la forma sbagliata: scrivi const { greet } = require(...) per una proprietà di un oggetto e const greet = require(...) per un valore assegnato.

module.exports ed exports: la trappola della riassegnazione

Prima che il tuo file venga eseguito, Node.js imposta exports = module.exports. Entrambi i nomi puntano a un unico oggetto, e require restituisce module.exports. Assegnare un nuovo valore a exports cambia solo la variabile locale:

const fs = require('fs');

// setup: the same export written two ways
fs.writeFileSync('broken.js', 'exports = { version: 2 };');
fs.writeFileSync('working.js', 'module.exports = { version: 2 };');

console.log('broken:', require('./broken'));
console.log('working:', require('./working'));

broken.js ha esportato {}, perché ora exports punta a un nuovo oggetto che nessuno restituisce. working.js ha esportato { version: 2 }.

La regola più semplice: scrivi sempre module.exports. Funziona in tutti i casi, e il codice dice quello che fa.

require restituisce lo stesso oggetto in cache

Node.js esegue il codice di un modulo una volta sola, la prima volta che viene richiesto, e mette in cache module.exports. Ogni require successivo dello stesso file restituisce quello stesso oggetto, quindi lo stato dentro un modulo è condiviso da tutti i file che lo caricano:

const fs = require('fs');

// setup: a module that counts and logs when it loads
fs.writeFileSync('counter.js', `
console.log('counter.js is running');
let count = 0;
module.exports = { next: () => ++count };
`);

const a = require('./counter');
const b = require('./counter.js');

a.next();
a.next();
console.log('b sees', b.next());
console.log('same object:', a === b);

counter.js is running è comparso una volta sola, b.next() ha restituito 3 e a === b è true, perché la chiave della cache è il path del file risolto e ./counter e ./counter.js puntano allo stesso file. Per questo una connessione al database o un oggetto di configurazione creato in un modulo è condiviso in tutta l'app.

module.exports e i moduli ES

I moduli ES usano invece export e import. Le forme corrispondono così:

// CommonJS                              // ES modules
module.exports = greet;                  export default greet;
module.exports.add = add;                export { add };
const greet = require('./greet');        import greet from './greet.js';
const { add } = require('./math');       import { add } from './math.js';

Un modulo ES può fare import di un file CommonJS: il suo module.exports arriva come import di default. Da Node.js 22.12, anche require() può caricare un modulo ES che non ha await al livello principale. Per capire quale scegliere, vedi CommonJS e moduli ES.

Errori comuni

Mescolare exports.x con module.exports = ... nello stesso file. L'assegnazione sostituisce l'oggetto, quindi ogni exports.x scritto prima sparisce. Scegli uno stile per file.

Esportare un valore che cambia dopo. module.exports = { count } copia il numero al momento del caricamento; quando il modulo aggiorna count, i chiamanti vedono ancora il vecchio valore. Esporta una funzione che lo restituisce, come fa counter.js qui sopra.

Dimenticare ./. require('math') cerca un pacchetto in node_modules, non math.js accanto al tuo file. I file locali iniziano sempre con ./ o ../.