HTML Academy · Aula

Mapas de importação importmap

Mapeie especificadores de módulos simples para URLs com importmap.

Mapas de importação importmap é uma aula grátis de HTML Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de HTML Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de HTML Academy inclui 4 aulas no total.

O problema dos especificadores sem caminho

No Node, import "lodash" funciona porque o resolvedor encontra node_modules/lodash. Os navegadores não têm node_modules — precisam de uma URL real. Sem ajuda, import "lodash" gera o erro "Falha ao resolver o especificador de módulo".

O que os mapas de importações fazem

Um mapa de importações declara um dicionário JSON que associa especificadores sem caminho (e prefixos de URL) a URLs reais. O navegador consulta o mapa no momento da resolução do módulo, convertendo import "lodash" em uma busca pela URL que você configurou.

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/lodash@4.17.21",
    "preact": "https://esm.sh/preact"
  }
}
</script>

A ordem das declarações é importante

O mapa de importações deve aparecer antes de qualquer <script type="module"> que use especificadores sem caminho — depois que um módulo começa a resolver as importações, o mapa fica definido. Coloque o <script type="importmap"> próximo ao início do <head>.

Mapeamentos de prefixos

Entradas que terminam com barra correspondem a prefixos de URL: "@/": "/src/" faz qualquer import "@/utils/sum.js" apontar para /src/utils/sum.js. É assim que você simula a sintaxe de "apelido" normalmente aceita pelos empacotadores.

Versionamento por meio de mapa

Um mapa de importações centraliza as escolhas de versão: altere "react" de esm.sh/react@18 para esm.sh/react@19 em um único lugar, e todos os módulos que importam esse recurso usarão a nova URL. Sem um mapa de importações, cada local de importação tem sua própria versão definida diretamente.

Escopos

A chave scopes permite diferentes mapeamentos para diferentes partes do seu site. Dentro de /admin/, talvez você queira uma versão mais recente de uma dependência do que em /public/; os escopos permitem direcionar os mapeamentos por caminho.

{
  "imports": { "lodash": "https://esm.sh/lodash@4" },
  "scopes": {
    "/admin/": { "lodash": "https://esm.sh/lodash@5" }
  }
}

Um mapa por documento

Cada documento pode ter no máximo um <script type="importmap">. Colocar dois na mesma página é inválido; combine o conteúdo deles em um único bloco para reunir as entradas.

Mapas de importações externos

Você pode hospedar o mapa em uma URL externa com <script type="importmap" src="map.json">. O suporte dos navegadores é mais recente do que o dos mapas embutidos, mas atualmente é amplo; isso é útil quando você quer armazenar em cache um mapa grande separadamente do documento.

Geração de mapas de importações

Ferramentas como JSPM Generator e o modo --servedir do esbuild produzem mapas de importações automaticamente a partir de package.json. Os mapas gerados incluem todas as dependências transitivas, associando cada uma a uma URL de CDN — um fluxo de trabalho sem node_modules.

Suporte dos navegadores

Os mapas de importações estão disponíveis no Chrome, Edge, Safari e Firefox. Os navegadores mais antigos ignoram a tag <script type="importmap">, o que faz os especificadores sem caminho falharem. Para oferecer amplo suporte a versões legadas, compile com um empacotador que resolva os especificadores durante a compilação e sirva URLs simples.

Opção de compatibilidade

O recurso de compatibilidade ES Module Shims (es-module-shims.js) adiciona suporte a mapas de importações — e a vários recursos mais recentes — em navegadores antigos. Inclua-o antes do seu script de mapa de importações. A maioria dos projetos modernos dispensa esse recurso e depende do suporte nativo.

Verificação de conhecimento

Por que um <script type="importmap"> deve aparecer antes de qualquer script de módulo que use especificadores sem caminho?

Resumo

Os mapas de importações associam especificadores sem caminho e prefixos de URL a URLs reais, restaurando no navegador a forma de importação do Node, "import lodash". Declare-os uma vez por documento, antes de qualquer script de módulo, opcionalmente por meio de src externo, com escopos para substituições específicas por caminho. Combine-os com uma CDN (esm.sh, jsdelivr) para um fluxo de trabalho sem node_modules.

Perguntas Frequentes

A aula “Mapas de importação importmap” é grátis?

Sim — o texto completo de “Mapas de importação importmap” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de HTML Academy, atualize para CoddyKit PRO. O curso de HTML Academy inclui 4 aulas no total.

O que vou aprender em “Mapas de importação importmap”?

Mapeie especificadores de módulos simples para URLs com importmap. Você pratica HTML Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar HTML Academy?

Nenhuma experiência prévia é necessária. HTML Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Mapas de importação importmap”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de HTML Academy?

Sim. Cada aula de HTML Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para HTML Academy