A extensão de mapa de origem ignoreList

Melhoramos a experiência de depuração no Chrome DevTools com a extensão de mapa de origem ignoreList.

O Chrome DevTools analisa o campo ignoreList nos mapas de origem para ajudar a melhorar a experiência de depuração do desenvolvedor. Confira o stack trace a seguir no Console. O DevTools oculta automaticamente todos os frames de terceiros e mostra apenas os que são relevantes para o código.

Uma comparação dos resultados do stack trace.
A imagem mostra os stack traces antes e depois que o Chrome DevTools oferece suporte ao ignoreList. O recurso mais tarde oculta frames de terceiros irrelevantes para ajudar você a identificar problemas com mais rapidez durante a depuração.

O que é o ignoreList?

As extensões dos mapas de origem são campos adicionais que armazenam informações complementares sobre o mapa de origem. Esses campos têm o prefixo x_.

O Chrome DevTools usa o campo ignoreList (se fornecido) para filtrar o código gerado e permitir que os desenvolvedores Web se concentrem apenas no código que eles criaram. Por exemplo, veja o mapa de origem a seguir.

/* demo.js.map */

{
  "version": 3,
  "mappings": "AAAAA, ..."
  "sources": [
    "app.js",
    "components/Button.ts",
    "node_modules/.../framework.js",
    "node_modules/.../library.js",
    ...
  ],
  "ignoreList": [2, 3],
  ...
}

O campo sources mostra uma lista de fontes originais usadas pela entrada mappings. Assista a O que são mapas de origem? para saber como os mapeamentos funcionam.

Como os dois arquivos node_modules/…/frameworks.js e node_modules/.../library.js são scripts de terceiros, é possível especificar o campo ignoreList para indicar as posições deles no campo sources. O Chrome DevTools aplicará essas informações para ocultar frames desses arquivos ignorados.

Uma comparação do stack trace recolhido e expandido.
A imagem mostra os stack traces antes e depois de serem expandidos no console. Os frames ignorados ficam esmaecidos quando expandidos.

Isso também se aplica à Pilha de chamadas no painel Sources durante a depuração do ponto de interrupção.

Em segundo plano, o DevTools tem uma configuração extra ativada por padrão: Adicionar automaticamente scripts conhecidos de terceiros à lista de ignorados. Ele pode ser encontrado em DevTools > Configurações > Lista de ignorados.

Com o campo do mapa de origem ignoreList, é possível ocultar os arquivos ignorados no painel Origens para se concentrar no código.

Ocultar fontes na lista de ignorados.

Como preencher ignoreList

A boa notícia é que frameworks como o Angular e o Nuxt já configuram ignoreList nos mapas de origem. Faça upgrade para a versão mais recente e comece a usar. Você consegue melhorias no stack trace com facilidade.

Por outro lado, ferramentas de build, como Vite e Rollup (links em inglês), oferecem configurações para definir isso. Também existe um plug-in do webpack para isso.

Se você é mantenedor de frameworks ou bibliotecas, é essencial entender como implementar essas configurações para melhorar a experiência de depuração dos usuários. Consulte a seção a seguir para saber como o Angular e a Nuxt fizeram isso nos bastidores.

E se seu framework e ferramenta de build favoritos ainda não oferecerem suporte a ele?

Trabalhamos ativamente com modelos e criamos ferramentas para alcançar essas novas configurações. Você também pode ajudar notificando os mantenedores sobre esse recurso. Por exemplo, registre um problema no repositório.

Como alternativa, é possível adicionar manualmente scripts irrelevantes à Lista de ignorados diretamente da árvore de arquivos no DevTools > Fontes > Página para conseguir um resultado semelhante.

Estudos de caso: implementação do Nuxt e do Angular

Confira os dois estudos de caso a seguir.

ignoreList em Nuxt

A partir do Nuxt v3.3.1, o conteúdo do node_modules e do buildDir do Nuxt foi marcado como "para ser ignorado pelos depuradores".

Isso foi feito com uma mudança na configuração do build do Nuxt usando Vite e Rollup:

/* vite.config.ts */

const ctx: ViteBuildContext = {
  config: vite.mergeConfig(
  build: {
    rollupOptions: {
      output: {
        sourcemapIgnoreList: (relativeSourcePath) => {
          return relativeSourcePath.includes('/node_modules/') || relativeSourcePath.includes(ctx.nuxt.options.buildDir)
        },
      }
})

A equipe do DevTools gostaria de agradecer às equipes Vite e Nuxt por tornarem isso possível. Agradecemos seus esforços e colaboração, que foram essenciais para o sucesso dessa implementação. Agradecemos novamente às equipes Vite e Nuxt pelas suas contribuições!

ignoreList no Angular

No Angular v14.1.0, o conteúdo das pastas node_modules e webpack foi marcado como "para ignorar".

Isso foi conseguido com uma mudança em angular-cli, criando um plug-in que se conecta ao módulo Compiler do webpack.

O plug-in webpack, que nossos engenheiros criaram hooks no estágio PROCESS_ASSETS_STAGE_DEV_TOOLING, preenche o campo ignoreList nos mapas de origem com os recursos finais que o webpack gera e o navegador carrega.

const map = JSON.parse(mapContent) as SourceMap;
const ignoreList = [];

for (const [index, path] of map.sources.entries()) {
  if (path.includes('/node_modules/') || path.startsWith('webpack/')) {
    ignoreList.push(index);
  }
}

map[`ignoreList`] = ignoreList;
compilation.updateAsset(name, new RawSource(JSON.stringify(map)));

Para saber mais sobre outras melhorias na depuração do Angular no DevTools, consulte Estudo de caso: melhor depuração do Angular com o DevTools.

A equipe do Chrome DevTools gostaria de agradecer à equipe do Angular pelas contribuições inestimáveis para o sucesso dessa implementação. Seus esforços e sua colaboração foram essenciais, e agradecemos seu empenho. Agradecemos a todos, equipe do Angular, por tornar isso possível.