module.exports vs exports no Node.js, com exemplos

module.exports é o valor que um arquivo Node.js entrega para qualquer outro arquivo que o carregue com require(). Ele começa como um objeto vazio: adicione propriedades para exportar várias coisas, ou atribua um valor novo (uma função, uma classe) para exportar uma coisa só. exports é uma variável de atalho que aponta para o mesmo objeto, então exports.add = ... funciona, mas exports = ... quebra a ligação e não exporta nada.

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));

Ele imprimiu 5 20 3.14159, depois [ 'add', 'multiply', 'PI' ]. As três linhas de math.js adicionaram propriedades ao mesmo objeto, seja passando por module.exports ou por exports, e require('./math') retornou esse objeto.

Exportar uma função, uma classe ou um objeto

Quando um módulo tem uma coisa principal, atribua direto a module.exports. Quem chama recebe a própria função, não um objeto em volta dela:

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());

Ele imprimiu Hello, Ada e Grace (user). Se você vir TypeError: greet is not a function, quem chamou usou o formato errado: escreva const { greet } = require(...) para uma propriedade de objeto e const greet = require(...) para um valor atribuído.

module.exports vs exports: a armadilha da reatribuição

Antes de o seu arquivo rodar, o Node.js faz exports = module.exports. Os dois nomes apontam para um único objeto, e require retorna module.exports. Atribuir um valor novo a exports só muda a variável local:

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 exportou {}, porque exports agora aponta para um objeto novo que ninguém retorna. working.js exportou { version: 2 }.

A regra mais simples: escreva sempre module.exports. Funciona em todos os casos, e o código diz o que faz.

require retorna o mesmo objeto em cache

O Node.js roda o código de um módulo uma vez, na primeira vez que ele é chamado com require, e guarda module.exports em cache. Todo require seguinte do mesmo arquivo retorna esse mesmo objeto, então o estado dentro de um módulo é compartilhado por todos os arquivos que o carregam:

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 apareceu uma vez, b.next() retornou 3, e a === b é true, porque a chave do cache é o caminho resolvido do arquivo, e ./counter e ./counter.js resolvem para o mesmo arquivo. É por isso que uma conexão com banco de dados ou um objeto de configuração criado em um módulo é compartilhado pelo app inteiro.

module.exports e ES modules

Os ES modules usam export e import. As formas se correspondem assim:

// 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';

Um ES module pode fazer import de um arquivo CommonJS: o module.exports dele chega como o import default. Desde o Node.js 22.12, require() também consegue carregar um ES module que não tenha await no topo. Para saber quando escolher cada um, veja CommonJS vs ES modules.

Erros comuns

Misturar exports.x com module.exports = ... no mesmo arquivo. A atribuição substitui o objeto, então todo exports.x escrito antes dela se perde. Escolha um estilo por arquivo.

Exportar um valor que muda depois. module.exports = { count } copia o número no momento do carregamento; quando o módulo atualiza count, quem chamou continua vendo o valor antigo. Exporte uma função que o retorne, como counter.js faz acima.

Esquecer o ./. require('math') procura um pacote em node_modules, não o math.js ao lado do seu arquivo. Arquivos locais sempre começam com ./ ou ../.