
Uma maneira padronizada de empacotar código como módulos reutilizáveis estava faltando no ECMAScript durante a maior parte de sua história. Na ausência de uma solução integrada, a abordagem CommonJS (CJS) tornou-se o padrão de fato para o desenvolvimento do Node.js. Isso usa require e module.exports para consumir e fornecer pedaços de código:
// Import a module const fs = require("fs"); // Provide an export module.exports = () => "Hello World";
O ES2015, também conhecido como ES6, finalmente introduziu um sistema de módulos embutido próprio. Módulos ECMAScript ou ES (ESM) contam com o import e export sintaxe:
// Import a default export import fs from "fs"; // Provide a default export export default () => "Hello World"; // Import a named export import {helloWorld} from "./hello-world.js"; // Provide a named export export const helloWorld = () => "Hello World";
O Node.js oferece suporte padrão para ESM desde a v16. Nas versões anteriores, você precisava usar o --experimental-modules sinalizador para ativar o recurso. Embora os Módulos ES estejam agora marcados como estáveis e prontos para uso geral, a presença de dois mecanismos de carregamento de módulos diferentes significa que é um desafio consumir os dois tipos de código em um único projeto.
Neste artigo, veremos como usar Módulos ES com Node e o que você pode fazer para maximizar a interoperabilidade com pacotes CommonJS.
O básico
As questões são relativamente simples se você estiver iniciando um novo projeto e quiser contar com o ESM. Como o Node.js agora oferece suporte total, você pode dividir seu código em arquivos separados e usar import e export instruções para acessar seus módulos.
Infelizmente você precisa fazer algumas escolhas conscientes desde o início. Por padrão, o Node não suporta import e export dentro de arquivos que terminam com o .js extensão. Você pode adicionar um sufixo aos seus arquivos como .mjsonde o ESM está sempre disponível, ou modifique seu package.json arquivo para incluir "type": "module".
{
"name": "example-package",
"type": "module",
"dependencies": {
"..."
}
}Escolher a última rota geralmente é mais conveniente para projetos que usarão exclusivamente o ESM. O nó usa o type campo para determinar o sistema de módulo padrão para seu projeto. Esse sistema de módulos é sempre usado para lidar com .js arquivos. Quando não definido manualmente, o CJS é o sistema de módulo padrão para maximizar a compatibilidade com o ecossistema existente de código Node. Arquivos com qualquer .cjs ou .mjs extensões sempre serão tratadas como fonte no formato CJS e ESM, respectivamente.
Importando um módulo CommonJS do ESM
Você pode importar módulos CJS dentro de arquivos ESM usando um import declaração:
// cjs-module.cjs module.exports.helloWorld = () => console.log("Hello World"); // esm-module.mjs import component from "./cjs-module.cjs"; component.helloWorld();
component será resolvido para o valor do módulo CJS module.exports. O exemplo acima mostra como você pode acessar exportações nomeadas como propriedades de objeto no nome de sua importação. Você também pode acessar exportações específicas usando a sintaxe de importação nomeada do ESM:
import {helloWorld} from "./cjs-module.cjs"; helloWorld();
Isso funciona por meio de um sistema de análise estática que varre os arquivos CJS para calcular as exportações que eles fornecem. Essa abordagem é necessária porque o CJS não entende o conceito de “exportação nomeada”. Todos os módulos CJS têm uma exportação – as exportações “nomeadas” são realmente um objeto com vários pares de valor de propriedade.
Devido à natureza do processo de análise estática, é possível que alguns padrões de sintaxe raros não sejam detectados corretamente. Se isso acontecer, você terá que acessar as propriedades necessárias por meio do objeto de exportação padrão.
Importando um módulo ESM do CJS
As coisas ficam mais complicadas quando você deseja usar um novo módulo ESM no código CJS existente. Você não pode escrever o import declaração dentro dos arquivos CJS. No entanto a dinâmica import() sintaxe funciona e pode ser emparelhada com await para acessar os módulos de forma relativamente conveniente:
// esm-module.mjs const helloWorld = () => console.log("Hello World"); export {helloWorld}; // esm-module-2.mjs export default = () => console.log("Hello World"); // cjs-module.cjs const loadHelloWorld = async () => { const {helloWorld} = await import("./esm-module.mjs"); return helloWorld; }; const helloWorld = await loadHelloWorld(); helloWorld(); const loadHelloWorld2 = async() => { const helloWorld2 = await import("./esm-module-2.mjs"); return helloWorld2; }; const helloWorld2 = await loadHelloWorld2(); helloWorld2();
Essa estrutura pode ser usada para acessar de forma assíncrona as exportações padrão e nomeadas de seus módulos ESM.
Recuperando o caminho do módulo atual com módulos ES
Os módulos ES não têm acesso a todas as variáveis globais familiares do Node.js disponíveis em contextos CJS. além do mais require() e module.exportsvocê não poderá acessar o __dirname ou __filename constantes também. Eles são comumente usados por módulos CJS que precisam conhecer o caminho para seu próprio arquivo.
Os arquivos ESM podem ler import.meta.url para obter esta informação:
console.log(import.meta.url); // file:///home/demo/module.mjs
A URL retornada fornece o caminho absoluto para o arquivo atual.
Por que todas as incompatibilidades?
As diferenças entre CJS e ESM são muito mais profundas do que simples mudanças sintáticas. CJS é um sistema síncrono; quando você require() um módulo, o Node o carrega direto do disco e executa seu conteúdo. ESM é assíncrono e divide as importações de script em várias fases distintas. As importações são analisadas, carregadas de forma assíncrona de seu local de armazenamento e executadas assim que todas as suas próprias importações forem recuperadas da mesma maneira.
O ESM foi projetado como uma solução moderna de carregamento de módulos com amplas aplicações. É por isso que os módulos ESM são adequados para uso em navegadores da Web: eles são assíncronos por design, portanto, redes lentas não são um problema.
A natureza assíncrona do ESM também é responsável pelas limitações em torno de seu uso no código CJS. Os arquivos CJS não são compatíveis com o nível superior await então você não pode usar import sozinho:
// this... import component from "component.mjs"; // ...can be seen as equivalent to this... const component = await import("component.mjs"); // ...but top-level "await" isn't available in CJS
Portanto, você tem que usar a dinâmica import() estrutura dentro de um async função.
Você deve mudar para módulos ES?
A resposta simples é sim. Os Módulos ES são a maneira padronizada de importar e exportar código JavaScript. O CJS deu ao Node um sistema de módulos quando a linguagem não tinha o seu próprio. Agora que está disponível, é melhor para a saúde a longo prazo da comunidade adotar a abordagem descrita pelo padrão ECMAScript.
O ESM também é o sistema mais poderoso. Por ser assíncrono, você obtém importações dinâmicas, importações remotas de URLs e desempenho aprimorado em algumas situações. Você também pode reutilizar seus módulos com outros runtimes JavaScript, como código que é entregue diretamente aos navegadores da Web por meio de <script type="module"> tags HTML.
No entanto, a migração continua sendo um desafio para muitos projetos Node.js existentes. CJS não vai embora tão cedo. Enquanto isso, você pode facilitar a transição oferecendo exportações CJS e ESM para suas próprias bibliotecas. Isso é melhor alcançado escrevendo um wrapper ESM fino em torno de qualquer exportação CJS existente:
import demoComponent from "../cjs-component-demo.js"; import exampleComponent from "../cjs-component-example.js"; export {demoComponent, exampleComponent};
Coloque este arquivo dentro de um novo esm subdiretório em seu projeto. Adicionar um package.json ao lado dele contendo o {"type": "module"} campo.
A seguir atualize o package.json na raiz do seu projeto para incluir o seguinte conteúdo:
{
"exports": {
"require": "./cjs-index.js",
"import": "./esm/esm-index.js"
}
}Isso diz ao Node para fornecer seu ponto de entrada CJS quando os usuários do seu pacote require() uma exportação. Quando import for usado, seu script wrapper ESM será oferecido em vez disso. Esteja ciente de que essa funcionalidade de mapa de importação também traz outro efeito colateral: os usuários serão limitados apenas às exportações fornecidas pelo seu arquivo de ponto de entrada. Carregando arquivos específicos por meio de caminhos no pacote (import demo from "example-package/path/to/file.js) é desabilitado quando um mapa de importação está presente.
Resumo
O cenário do módulo Node.js pode ser doloroso, especialmente quando você precisa de compatibilidade com CJS e ESM. Embora as coisas tenham melhorado com a estabilização do suporte ao ESM, você ainda precisa decidir antecipadamente qual sistema de módulos deve ser o “padrão” para seu projeto. O carregamento de código do “outro” sistema é possível, mas muitas vezes desconfortável, principalmente quando o CJS depende do ESM.
As coisas melhorarão gradualmente à medida que mais projetos importantes passarem a adotar o ESM como sua abordagem preferida. No entanto, com tanto código CJS existente, a migração em massa não é realista e é provável que ambos os mecanismos sejam usados lado a lado – com todas as compensações que isso implica – por vários anos.
Se você estiver iniciando uma nova biblioteca, certifique-se de estar distribuindo código compatível com ESM e tente usá-lo como seu sistema padrão sempre que possível. Isso deve ajudar o ecossistema do Node a convergir no ESM, realinhando-o com os padrões do ES.
Fonte Adicione ao Google Notícias



