Erro Uncaught SyntaxError: Cannot Use Import Statement Outside a Module

Ao desenvolver aplicações web modernas com JavaScript, uma das funcionalidades mais utilizadas é o sistema de módulos, permitindo a organização e reutilização de código de forma eficiente. No entanto, muitos desenvolvedores encontram um erro comum ao tentar usar o import em seus scripts:

Uncaught SyntaxError: Cannot Use Import Statement Outside a Module

Esse erro indica que houve uma tentativa de usar a sintaxe de importação do ECMAScript Modules (ESM) fora do contexto adequado. Neste artigo, vamos explorar as causas desse problema, apresentar soluções práticas e dicas úteis para resolver e evitar esse erro em seus projetos.

uncaught-syntaxerror-cannot-use-import-statement-outside-a-module

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

Este erro ocorre quando o navegador ou o interpretador JavaScript identifica uma tentativa de utilizar a declaração import em um contexto que não é reconhecido como um módulo válido. Segundo uma citação do engenheiro de software Chris Coleman:

“Para usar a sintaxe de importação e exportação do ECMAScript, seu arquivo precisa ser reconhecido como um módulo pelo ambiente de execução.”

Como funciona o sistema de módulos no JavaScript?

Os módulos em JavaScript permitem dividir o código em partes menores, que podem ser importadas e exportadas entre si. Existem duas principais formas de usar módulos:

CommonJS (mais utilizado em Node.js)
ES Modules (ESM) (padrão html e atualmente recomendado em browsers)

No entanto, para que o sistema de módulos funcione corretamente, é preciso configurar o ambiente de execução de forma adequada.

Causas comuns do erro

A seguir, apresentamos as principais razões que levam ao erro "Cannot Use Import Statement Outside a Module".

1. Arquivo não reconhecido como módulo

Por padrão, arquivos JavaScript não são tratados como módulos a menos que sejam explicitamente configurados assim. No navegador, isso ocorre se o atributo type="module" não estiver presente na tag <script>.

2. Configuração incorreta do arquivo `package.json`

Em projetos Node.js, para usar .js como módulo ESM, é necessário definir "type": "module" no arquivo package.json.

3. Uso de importação em scripts inline

O uso de <script src="script.js"> sem o atributo type="module" gera o erro, pois o navegador interpreta o script como uma script comum, não um módulo.

4. Caminho incorreto ou indisponível do módulo

Se o caminho do arquivo importado não estiver correto, o navegador pode interpretar como uma tentativa de usar importação fora do contexto.

Como resolver o erro

Para resolver o erro "Uncaught SyntaxError: Cannot Use Import Statement Outside a Module", confira as soluções abaixo.

1. Adicionar `type="module"` na tag `<script>`

No HTML, a maneira mais comum de garantir que o navegador reconheça seu script como módulo é incluir o atributo type="module":

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

Exemplo completo:

<!DOCTYPE html><html lang="pt-br"><head><meta charset="UTF-8" /><title>Exemplo de Módulo JavaScript</title></head><body><script type="module" src="app.js"></script></body></html>

2. Configurar o `package.json` corretamente em projetos Node.js

Se estiver utilizando Node.js, garanta que seu package.json declare:

{  "type": "module"}

Assim, os arquivos .js serão interpretados como módulos ECMAScript. Caso contrário, será necessário usar a extensão .mjs para seus arquivos de módulo.

3. Utilizar a extensão correta nos caminhos do import

No navegador, ao importar módulos, é preciso especificar a extensão do arquivo, por exemplo:

import { minhaFuncao } from './meumodulo.js';

Se a extensão não for fornecida, o carregador pode resultar no erro.

4. Verificar o servidor de desenvolvimento

Para evitar erros relacionados à CORS ou ao modo de carregamento, sempre utilize um servidor de desenvolvimento (como o Live Server no VSCode) ao desenvolver com módulos ES.

Tabela Comparativa de Configuração

Situação	Correção	Considerações
Script no HTML sem `type="module"`	Adicionar `type="module"`	Essencial para scripts com `import` e `export`
Arquivo `package.json` sem `"type":"module"`	Inserir `"type":"module"`	Necessário para projetos Node.js com ES Modules
Import sem extensão (`import ... from './mymodule'`)	Especificar extensão (`.js`)	Navegadores requerem extensão explícita
Uso em ambiente local sem servidor	Utilizar servidor local (ex: Live Server)	Evita problemas de CORS e carregamento

Perguntas Frequentes (FAQs)

1. Por que meu código funciona no Node.js mas dá erro no navegador?

Porque o Node.js interpreta .js como CommonJS por padrão, a menos que o package.json especifique "type": "module". Já os navegadores exigem o atributo type="module" na tag <script> para reconhecer scripts como módulos ES.

2. Posso usar import em scripts inline no HTML?

Sim, mas é necessário usar <script type="module">. Exemplo:

<script type="module">  import { minhaFuncao } from './meumodulo.js';  minhaFuncao();</script>

3. É possível usar import sem extensões de arquivo?

Não na maioria dos navegadores. É obrigatório especificar a extensão do arquivo, como .js.

4. Como sei se meu ambiente está configurado corretamente como módulo?

Verifique a configuração do arquivo package.json, o atributo type e o uso do atributo type="module" na tag <script> no HTML.

Dicas finais para evitar o erro

Sempre inclua type="module" nas tags <script> que usam import.
Configure package.json corretamente em projetos Node.js.
Use servidores locais ao desenvolver, evitando problemas de CORS.
Seja explícito com o caminho e extensão do arquivo importado.
Teste seu código em diferentes navegadores para garantir compatibilidade.

Conclusão

O erro "Uncaught SyntaxError: Cannot Use Import Statement Outside a Module" é comum ao trabalhar com módulos JavaScript, especialmente em ambientes que exigem configuração explícita. Com a compreensão das causas e a aplicação das soluções apresentadas, os desenvolvedores podem evitar esse problema e aproveitar ao máximo as funcionalidades modernas do JavaScript para criar aplicações mais organizadas e eficientes.

Lembre-se sempre de configurar seu ambiente corretamente, usar as tags <script> com type="module" e manter uma estrutura bem definida de arquivos e caminhos.

Referências

Se precisar de mais informações ou ajuda prática, consulte comunidades de desenvolvedores ou fóruns especializados. Boa codificação!