Em ambientes modernos de JavaScript, o uso de import e export está intrinsecamente ligado aos módulos. Quando o código tenta importar algo sem que esteja dentro de um módulo, surge o erro “Cannot use import statement outside a module” (ou variações como este pode aparecer na documentação ou mensagens de console). Este artigo mergulha fundo no tema, explicando por que esse problema ocorre, como identificar as causas e, principalmente, como resolvê-lo de forma prática em diferentes cenários — Node.js, navegadores e ambientes de build.
O que são módulos de JavaScript e por que eles importam
Definição básica de módulos
Um módulo em JavaScript é um arquivo que exporta partes de sua funcionalidade (funções, objetos, variáveis) e pode importar partes de outros módulos. Esse encapsulamento reduz conflitos de nomes, define dependências de forma clara e permite que o código seja reutilizado com segurança em diferentes contextos.
ES Modules (ESM) vs CommonJS (CJS)
Existem dois modelos amplamente usados para carregar código: ES Modules (import/export) e CommonJS (require/module.exports). A distinção é essencial para entender o erro “cannot use import statement outside a module”. Em ambientes que utilizam CommonJS por padrão, o import nem sempre é permitido sem uma configuração específica. Em contrapartida, em ES Modules, o padrão é exatamente o uso de import/export. A correta seleção de tipo de módulo impacta diretamente se o erro aparece ou não.
Como o navegador trata módulos
Nos navegadores modernos, para habilitar módulos precisamos indicar explicitamente no HTML que aquele script é um módulo, usando o atributo type=”module” na tag <script>. Sem esse atributo, o conteúdo é tratado como script comum e não suporta import/export. Isso é uma das causas mais comuns do erro quando se tenta rodar código em cliente sem a devida configuração.
Possíveis causas do erro: quando não é possível usar import statement inside a module
Script sem type=”module” no HTML
Se o seu código usa import e o script não está marcado como módulo, o navegador irá reclamar com mensagens semelhantes a Cannot use import statement outside a module. Verifique a tag <script> que carrega o arquivo e inclua type="module" quando for necessário.
Arquivos não tratados como módulos no Node.js
No Node.js moderno, é comum rodar código com módulos. Se você estiver tentando usar import sem ter configurado o ambiente para ES Modules, o Node pode apresentar o mesmo erro. As maneiras mais comuns de resolver são: definir “type”: “module” no package.json, usar a extensão .mjs para arquivos ou usar uma ferramenta de bundling que converta para uma forma suportada pelo ambiente.
Configurações inconsistentes entre arquivos .js e .mjs
Em projetos com mistura de .js e .mjs, o sistema pode entender alguns arquivos como módulos e outros como scripts comuns. Garantir uma configuração unificada ajuda a evitar o erro cannot use import statement outside a module.
Transpiladores e bundlers que não preservam o módulo
Ferramentas como Babel, Webpack, Rollup e outros transformam código para suportar ambientes mais antigos. Se a configuração do bundler não mantiver o formato de módulo (ESM), o import pode falhar em tempo de execução. Verifique as opções de saída (output) para garantir que o código final ainda utilize import/export onde for necessário.
Como resolver o erro em Node.js: passos práticos
Opção 1: declarar o projeto como módulo (type: module)
A forma mais direta de habilitar import/export no Node.js é indicar que o projeto usa ES Modules. Adicione no package.json a propriedade "type": "module". Quando feito, arquivos .js passam a ser interpretados como ES Modules por padrão.
{
"name": "meu-projeto",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node index.js"
}
}
Opção 2: usar a extensão .mjs
Outra abordagem é renomear seus arquivos JavaScript que usam import/export para a extensão .mjs. Nesse caso, o Node trata esses arquivos estritamente como ES Modules, independentemente do conteúdo do package.json.
Opção 3: manter CommonJS com require
Se você não quer adotar ES Modules de forma ampla, pode manter o código usando CommonJS e substituir import/export por require/module.exports. Essa é uma mudança de estilo, mas evita o erro em ambientes que ainda não suportam ES Modules de forma geral.
Opção 4: usar dynamic import em partes específicas
Em alguns cenários, é possível manter a maior parte do código em CommonJS e usar dynamic import (import()) somente em trechos que precisam de carregamento assíncrono de módulos. Isso pode contornar o problema sem grandes refatorações.
Como resolver o erro em navegadores: script type=”module” e beyond
Uso correto de <script type="module">
Para que o código com import/export funcione no navegador, o script principal precisa ser marcado como módulo. Além disso, os caminhos de import devem ser relativos ou completos e as importações devem ser compatíveis com o formato de módulo.
Carregar módulos de forma assíncrona
Os módulos são carregados de forma assíncrona por padrão. Use import para trazer dependências apenas quando necessário, o que também pode impactar a performance e evitar problemas de tempo de carregamento.
Configurações de CORS para módulos
Em alguns cenários, especialmente ao servir módulos de um servidor, as políticas de CORS podem impedir o carregamento de módulos entre domínios. Garanta que o servidor permita o carregamento de arquivos ES Module e que os cabeçalhos estejam corretos.
Boas práticas com bundlers e ferramentas modernas
Por que usar bundlers?
Bundlers ajudam a agrupar várias dependências, otimizar o código e resolver automaticamente diferenças entre ambientes. Eles também podem impor o uso de módulos de uma forma que minimize problemas com o erro cannot use import statement outside a module durante o desenvolvimento ou a produção.
Configurações comuns com Webpack, Rollup e Vite
Em ferramentas modernas, é comum configurar suporte a ES Modules e emitir bundles que rodam tanto em browsers quanto em ambientes Node.js. Verifique a seção de outputs, target e modules do seu bundler para assegurar compatibilidade com import/export.
Erros comuns, causas frequentes e como diagnosticar
Erro ao iniciar sem type: module
Quando você vê a mensagem cannot use import statement outside a module, verifique a origem do arquivo que está tentando importar. Se for um script carregado diretamente por uma tag <script>, confirme se há type=”module” presente. Em muitos casos, a remoção de uma dependência não compatível ou a mudança para um formato de módulo resolve rapidamente.
Diferenças entre ambiente de execução e origem do script
Às vezes, o código funciona em ambiente de desenvolvimento, mas falha ao ser empacotado ou servido por um servidor específico. Verifique se o ambiente de execução (navegador, Node, ou plataforma de hospedagem) está alinhado com a configuração de módulos do projeto.
Sequência de carregamento de dependências
O erro pode ocorrer quando uma dependência tenta importar algo que ainda não foi carregado. Garanta uma ordem correta de importação, evitando circular dependencies, que podem dificultar a resolução de módulos no tempo de execução.
Casos de uso comuns e soluções rápidas
Projeto simples no navegador
Se você tem um projeto mínimo com index.html e scripts que utilizam import/export, adicione: <script type="module" src="main.js"></script> no HTML e verifique que as importações utilizam caminhos corretos.
Aplicação Node.js com várias pastas
Em monorepos ou aplicativos com várias pastas, use o package.json com "type": "module" ou mantenha a extensão .mjs para os arquivos que contêm imports. Além disso, reflita as importações relativas entre pastas para evitar caminhos incorretos.
Projeto com TypeScript
Ao usar TypeScript, garanta que a configuração de module no tsconfig esteja alinhada com a forma de execução pretendida. Em projetos que rodam no Node.js como ES Modules, use module": "ESNext" ou equivalente, e certifique-se de compilar para um formato compatível com o ambiente-alvo.
Como o SEO e a consistência textual ajudam no ranking
Para alcançar boa visibilidade com o tema “cannot use import statement outside a module”, é importante manter a consistência do termo ao longo do artigo, inclusive em títulos e subtítulos. Repetir a frase exata em contextos relevantes facilita o rastreamento por motores de busca, ao mesmo tempo em que o conteúdo permanece útil para leitores que estão aprendendo a solucionar esse problema. Além disso, explorar variações como o uso de capitalização em “Cannot use import statement outside a module” em títulos pode atrair tanto buscas em inglês quanto usuários que já conhecem o problema em sua forma original.
Guia rápido de verificação: checklist para ninguém ficar preso no erro
Checklist de ambientes de navegador
- Verificar se o arquivo HTML carrega scripts com type=”module”
- Checar caminhos de import: relativos, com extensão, sem typos
- Confirmar se as dependências estão disponíveis no servidor
Checklist de ambientes Node.js
- Decidir entre type: module ou extensão .mjs
- Se usar TypeScript, alinhar tsconfig com o alvo de módulo
- Garantir que as dependências sejam compatíveis com ES Modules
Checklist rápido de bundlers
- Verificar que o bundle mantém o formato de módulo
- Certificar-se de que as importações não são substituídas por require inadvertidamente
- Testar o código em ambiente de produção com o servidor correspondente
Conclusão: entendendo redes de módulos para evitar o erro
O erro cannot use import statement outside a module está intrinsecamente ligado à forma como JavaScript organiza, carrega e executa código. A melhor forma de evitar esse problema é entender o tipo de módulo que seu ambiente requer, configurar adequadamente as opções de projeto e adotar práticas consistentes de importação e exportação. Com as estratégias apresentadas neste artigo, você poderá diagnosticar rapidamente a origem do problema, aplicar a correção correta — seja ajustando o script, seja optando por ES Modules/CommonJS conforme o caso — e manter seu código funcionando sem interrupções, seja no navegador, seja no servidor.
FAQ rápida sobre o tema
É possível usar import sem tornar o projeto um módulo?
Não, para usar import/export é necessário que o código rode dentro de um módulo. Caso contrário, ocorre o erro cannot use import statement outside a module.
Como saber se meu arquivo é tratado como módulo?
Em Node.js, se o package.json contém “type”: “module” ou se o arquivo tem a extensão .mjs, ele é tratado como módulo. Em browsers, é necessário type="module" na tag <script>.
O que fazer se não puder alterar o servidor?
Considere a adoção de bundlers que transformem import/export para uma forma compatível, ou migre gradualmente para ES Modules com TypeScript, mantendo a compatibilidade com o ambiente alvo.
Encerramento
Dominar o conceito de módulos e suas regras de carregamento é essencial para qualquer desenvolvedor moderno. Ao entender as nuances por trás do erro Cannot use import statement outside a module ou da sua variação em inglês, você ganha agilidade para diagnosticar, planejar e aplicar mudanças que mantêm seu código limpo, rápido e compatível com as melhores práticas de desenvolvimento. Continue explorando, testando e fortalecendo suas habilidades em modularização para elevar a qualidade de seus projetos.
Recursos adicionais para aprofundar o tema
Documentação oficial
Leia sobre ES Modules, Node.js e configurações de bundlers para obter orientações atualizadas sobre como trabalhar com import/export de forma eficiente.
Práticas recomendadas
Adote convenções consistentes de nomenclatura de arquivos, use extensões apropriadas (.mjs para módulos, .js para scripts conforme a configuração) e mantenha um guia de configuração de módulos no seu repositório para facilitar equipes futuras.
Exemplos de solução rápida
Para uma correção imediata, identifique o arquivo que dispara o erro e adote uma das estratégias discutidas: adicionar type=”module” ao script, mudar para .mjs, ou reconfigurar o projeto para ES Modules de forma consistente.