Erro: Cannot Use Import Statement Outside a Module - Guia Completo

Ao trabalhar com JavaScript moderno, especialmente com módulos ES6, muitos desenvolvedores encontram o erro "Cannot Use Import Statement Outside a Module". Este erro ocorre quando o interpretador JavaScript não reconhece seu arquivo como um módulo, impedindo o uso da declaração import. Compreender as causas, soluções e boas práticas relacionadas a essa mensagem é essencial para evitar frustrações e garantir um desenvolvimento eficiente.

Este artigo apresenta um guia completo para entender, identificar e solucionar o erro "Cannot Use Import Statement Outside a Module", abordando conceitos básicos, configurações de ambientes diversas, exemplos práticos e dicas para evitar problemas semelhantes.

O que significa o erro "Cannot Use Import Statement Outside a Module"?

Esse erro indica que o interpretador JavaScript trata o arquivo como um código comum (script), e não como um módulo ES6. Portanto, não reconhece a sintaxe import. Essa incompatibilidade acontece por diferenças de configuração entre ambientes de execução, como navegadores, Node.js ou ferramentas de build.

Principais razões para o erro

Causa	Descrição	Exemplo
Arquivo não configurado como módulo	O interpretador não interpreta o arquivo como módulo.	`type: 'module'` ausente no `package.json` ou extensão `.mjs`.
Configuração do ambiente incorreta	Ambiente de execução não está configurado para entender módulos ES6.	Node.js habilitado para módulos via `.js`, mas sem `type: 'module'`.
Extensão de arquivo inadequada	Usar `.js` sem configuração adequada pode gerar problemas em ambientes específicos.	Usar `.js` sem configuração no `package.json` no Node.js.

Como funciona o suporte a módulos em diferentes ambientes

Módulo em navegadores

Navegadores modernos suportam módulos JavaScript usando o atributo type="module" na tag <script>. Isso indica ao navegador que o script deve ser tratado como um módulo ES6.

<script type="module" src="app.js"></script>

Se esse atributo faltar, o navegador tentará interpretar o arquivo como uma script tradicional, causando o erro.

Módulo em Node.js

Desde a versão 12, o Node.js oferece suporte nativo a módulos ES6, mas requer configurações específicas.

Configuração	Como fazer	Observação
`type: 'module'` no `package.json`	Adicione `"type": "module"` no seu `package.json`.	Necessário para usar import/export em arquivos `.js`.
Renomear arquivos para `.mjs`	Alterne para `.mjs`, que é reconhecido como módulo.	Alternativa se não desejar modificar `package.json`.

Citação:
"A compreensão do ambiente de execução é fundamental para evitar erros comuns ao usar módulos em JavaScript." — Especialistas em desenvolvimento web

Como solucionar o erro "Cannot Use Import Statement Outside a Module"

1. Verifique a configuração do seu projeto

Se estiver usando Node.js, confira se o seu package.json possui o campo:

{  "type": "module"}

Se não, adicione-o para habilitar a sintaxe de módulos ES6.

2. Renomeie seus arquivos

Use a extensão .mjs ao invés de .js, principalmente em projetos mais antigos ou ao trabalhar com scripts específicos.

3. Configure seu ambiente de execução

No navegador: garanta que a tag <script> possua type="module".

<script type="module" src="app.js"></script>

No Node.js: além de type: 'module', certifique-se de usar uma versão compatível (>=12).

4. Verifique a sintaxe do seu código

Garanta que todas as declarações de import estejam no topo do arquivo e sejam compatíveis com o ambiente.

5. Use ferramentas de build

Ferramentas como Babel, Webpack ou Rollup podem transpilar seu código ES6 para versões compatíveis com diferentes ambientes.

Guia passo a passo para resolver o erro

Passo 1: Confirmar a versão do Node.js (ou navegador)

node -v

Se for menor que 12, atualize para uma versão mais recente.

Passo 2: Configurar `package.json` com `"type": "module"`

{  "name": "meu-projeto",  "version": "1.0.0",  "type": "module"}

Passo 3: Ajustar o código

// app.jsimport { soma } from './soma.js';console.log(soma(2, 3));

Passo 4: Executar o projeto

node app.js

Se tudo estiver configurado corretamente, o erro será resolvido.

Exemplos práticos de configurações corretas e incorretas

Situação	Configuração correta	Configuração incorreta
Node.js com `package.json`	`"type": "module"` presente	Ausente
Arquivo `app.js`	`import { ... } from '...'` sem problema	`import` causando erro devido à ausência do `type: 'module'`
Navegador	`<script type="module" src="app.js"></script>`	`<script src="app.js"></script>` sem o atributo `type`

Perguntas Frequentes

1. Como uso o `import` em arquivos Node.js que não sejam módulos?

Resposta: Você precisa configurar seu package.json com "type": "module" ou renomear seus arquivos para .mjs. Além disso, certifique-se de que seu ambiente suporta módulos ES6.

2. Posso usar `import` e `require` no mesmo projeto?

Resposta: Sim, mas é recomendado manter uma consistência na configuração. Em projetos modernos, prefira usar apenas módulos ES6 com import. Para usar ambas, pode ser necessário configurar o Babel ou ferramentas de build específicas.

3. Como faço para que o navegador suporte minhas importações?

Resposta: Certifique-se de que suas tags <script> possuem o atributo type="module" e seus arquivos estão acessíveis na mesma origem (domínio).

4. O erro também pode acontecer em ambientes de build? Como evitar?

Resposta: Sim. Use ferramentas como Babel ou Webpack que transpilem seu código para um formato compatível. Assim, você evita problemas de suporte de ambiente.

Conclusão

O erro "Cannot Use Import Statement Outside a Module" é comum ao trabalhar com módulos JavaScript, especialmente ao migrar de scripts tradicionais. Entender as diferenças de configuração entre ambientes, usar as opções corretas no seu projeto e seguir boas práticas garantem que seu código funcione de forma estável.

Para evitar esse problema, sempre verifique a configuração do seu ambiente de execução, adapte seus arquivos e utilize ferramentas de build quando necessário. Assim, o uso de módulos ES6 se torna mais eficiente, seguro e compatível.

Referências

Se precisar de mais ajuda ou exemplos específicos, consulte um desenvolvedor profissional ou comunidades de desenvolvimento como Stack Overflow.