Como desenvolvedores de JavaScript e TypeScript, frequentemente encontramos erros inesperados ao trabalhar com diferentes sistemas de módulos. Um problema comum é o erro “Não é possível usar a instrução de importação fora de um módulo”. Geralmente surge ao trabalhar com módulos ES modernos (ESM) ou lidar com configurações envolvendo empacotadores como ambientes Webpack, Babel ou Node.js. Neste blog, exploraremos o que causa esse erro, por que ele acontece e soluções práticas para resolvê-lo.

O que esse erro significa?

O erro “Não é possível usar a instrução de importação fora de um módulo" é autoexplicativo: ocorre quando o JavaScript encontra uma instrução de importação fora de um módulo ES válido. Em JavaScript, os sistemas de módulo determinam como o código é dividido em vários arquivos e como eles interagem entre si. Módulos ES (importar/exportar) e CommonJS (require/module.exports) são os dois sistemas de módulos principais.

Se o JavaScript não reconhecer seu código como um módulo ES, isso gerará este erro.

O que causa o erro “Não é possível usar a instrução de importação fora de um módulo”?

Isso geralmente ocorre quando JavaScript/TypeScript encontra uma instrução de importação fora do contexto de um módulo. O que significa que o arquivo do qual você está tentando importar não é reconhecido como um módulo ES.

Aqui estão alguns motivos mais comuns pelos quais esse erro pode ocorrer:

• Node.js usando CommonJS por padrão: Por padrão, Node.js usa módulos CommonJS (CJS), não módulos ES. Isso significa que a sintaxe de importação/exportação não é suportada nativamente, a menos que seja especificada.

• Babel/Webpack mal configurado: Ao agrupar seu código, ferramentas como Babel ou Webpack podem não estar configuradas para lidar com módulos ES corretamente, especialmente se o ambiente de destino não os suportar nativamente.

• "type": "module" ausente em package.json: se você estiver usando módulos ES em um projeto Node.js, será necessário especificá-lo explicitamente adicionando "type" : "module" em seu package.json.

• Incompatibilidade de extensão de arquivo: Às vezes, usar .js em vez de .mjs para módulos ES ou vice-versa pode resultar neste erro.

Soluções passo a passo

Aqui estão algumas soluções para corrigir o erro “Não é possível usar a instrução de importação fora de um módulo”:

• Ativar módulos ES em Node.js:

O caso mais comum é quando você está trabalhando com Node.js, cujo padrão são módulos CommonJS. Para ativar os módulos ES, faça o seguinte:

Método 1: Modificar package.json:

{
  "type": "module"
}

Ao adicionar "type": "module" ao seu package.json, você está dizendo ao Node.js para tratar todos os arquivos .js como módulos ES.

Método 2: renomear arquivos para .mjs:

Se não quiser modificar seu package.json, você pode renomear seus arquivos para .mjs (por exemplo, index.mjs) para indicar explicitamente que eles são módulos ES.

• Atualizar configuração do Babel/Webpack:

Se você estiver usando Babel ou Webpack, certifique-se de que eles estejam configurados para lidar com módulos ES corretamente. Para Babel, você pode usar o plugin @babel/preset-modules. Para Webpack, defina module como false em sua configuração.

Para Babel: atualize o arquivo .babelrc ou babel.config.json:

{
  "presets": ["@babel/preset-modules"]
}

Para Webpack: atualize o arquivo webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

• Verifique o caminho de importação e a sintaxe:

Certifique-se de que seus caminhos de importação estejam corretos e que você esteja usando a sintaxe correta. Por exemplo, caminhos relativos devem começar com ./ ou ../.

Se você estiver importando um módulo de node_modules, certifique-se de que o pacote suporta módulos ES. Caso contrário, talvez seja necessário usar um empacotador como o Webpack para lidar com isso.

• Verifique novamente as extensões de arquivo:

Se você estiver usando módulos ES, certifique-se de que suas extensões de arquivo correspondam ao tipo de módulo. Use .mjs para módulos ES e .js para módulos CommonJS.

• .mjs: módulos ES
• .cjs: módulos CommonJS

Qual é a diferença entre módulos ES e módulos CommonJS?

Então, uma coisa que vem à mente é qual é a diferença entre módulos ES e módulos CommonJS? E por que existem dois sistemas de módulos diferentes em JavaScript?

Módulos ES

Os módulos ES são o sistema oficial de módulos JavaScript introduzido no ES6 (ES2015). Eles usam as palavras-chave import e export para definir dependências entre módulos. Os módulos ES são analisáveis ​​estaticamente, o que significa que as dependências são resolvidas em tempo de compilação, facilitando a otimização do código.

ES são carregados de forma assíncrona, o que permite melhor desempenho e carregamento paralelo de módulos. Eles também oferecem suporte a exportações nomeadas, exportações padrão e dependências cíclicas. Os módulos ES são amplamente suportados em navegadores modernos e Node.js (com o sinalizador "type": "module").

Módulos CommonJS

CommonJS é um sistema de módulo usado em Node.js e outros ambientes antes da introdução dos módulos ES. Os módulos CommonJS usam a função require para importar módulos e module.exports ou exportar para exportar valores. Os módulos CommonJS são carregados de forma síncrona, o que pode levar a problemas de desempenho.

Os módulos CommonJS não são suportados nativamente em navegadores, mas podem ser transpilados para módulos ES usando ferramentas como Babel ou Webpack. Os módulos CommonJS ainda são amplamente usados ​​em projetos Node.js, mas os módulos ES estão se tornando mais populares devido ao seu melhor desempenho e capacidade de análise estática.

A razão pela qual esses dois sistemas de módulos existem é devido à evolução do JavaScript e à necessidade de um sistema de módulos mais moderno e padronizado. Os módulos ES são o futuro dos módulos JavaScript, mas os módulos CommonJS ainda são amplamente utilizados em projetos e ambientes existentes.

Dicas de depuração

Se você tentou todas as soluções acima e ainda está enfrentando o erro, aqui estão algumas dicas adicionais de depuração:

• Verifique a versão do Node.js: certifique-se de estar executando o Node.js versão 12.x ou superior, pois o suporte aos módulos ES foi introduzido nativamente no Node.js 12. Se você estiver em uma versão mais antiga, os módulos ES não funcionarão. Atualize sua versão visitando o site do Node.js.

• Verifique o suporte do navegador: se você estiver trabalhando em um ambiente de navegador, certifique-se de que seu navegador seja compatível com módulos ES. A maioria dos navegadores modernos sim, mas versões mais antigas talvez não.

• Verifique erros de digitação: Às vezes, um simples erro de digitação em seu código pode causar esse erro. Verifique seu código em busca de erros ortográficos ou sintaxe incorreta.

• Use npx tsc para TypeScript: se você estiver usando TypeScript e encontrar esse erro, execute npx tsc para compilar seu código TypeScript em JavaScript, o que pode ajudar a detectar problemas.

Conclusão

O erro “Não é possível usar a instrução de importação fora de um módulo” é um problema comum enfrentado por desenvolvedores de JavaScript/TypeScript ao trabalhar com módulos ES. Ao entender por que esse erro ocorre e seguir as soluções passo a passo fornecidas neste blog, você pode resolvê-lo rapidamente e continuar criando código modular e de fácil manutenção.