Melhore 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
em 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 todos os frames de terceiros automaticamente e mostra somente os relevantes para seu código.
O que é o ignoreList
?
As extensões de 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 da Web se concentrem apenas no código que criam. Por exemplo, observe 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 vai aplicar essas informações para ocultar frames desses arquivos ignorados.
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 de terceiros conhecidos à lista de ignorados. Ela está disponível em DevTools > Settings > Ignore List.
Com o campo de mapa de origem ignoreList
, você tem a opção de ocultar os arquivos ignorados no painel Origens para se concentrar no código.
Como preencher ignoreList
A boa notícia é que frameworks como Angular e Nuxt já configuram o ignoreList
nos mapas de origem. Faça upgrade para a versão mais recente, e ela está pronta para uso. Você recebe melhorias no stack trace sem esforço.
Por outro lado, ferramentas de build como Vite e Rollup oferecem configurações para isso. Também existe um plug-in webpack para isso.
Se você é gerente de framework ou biblioteca, é 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 ver como o Angular e o Nuxt fizeram isso em segundo plano.
E se seu framework e ferramenta de build favoritos ainda não tiver suporte para eles?
Trabalhamos ativamente com estruturas e ferramentas para desenvolver essas novas configurações. Você também pode ajudar notificando os mantenedores sobre esse recurso. Por exemplo, é possível registrar um problema no repositório dele.
Como alternativa, você pode adicionar manualmente scripts irrelevantes à lista de ignorados diretamente da árvore de arquivos no painel DevTools > Sources > Page para conseguir um resultado semelhante.
Estudos de caso: implementação do Nuxt e do Angular
Dê uma olhada nos dois estudos de caso a seguir.
ignoreList
em Nuxt
A partir do Nuxt v3.3.1, o conteúdo de node_modules
e buildDir
do Nuxt foi marcado como "a ser ignorado pelos depuradores".
Isso foi feito por meio de uma mudança na configuração do build do Nuxt usando o Vite e o 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 da Vite e da Nuxt por tornar isso possível. Agradecemos seu esforço e colaboração, que foram essenciais para o sucesso dessa implementação. Agradecemos novamente às equipes do Vite e Nuxt por suas contribuições!
ignoreList
no Angular
A partir do Angular v14.1.0, o conteúdo das pastas node_modules
e webpack
foi marcado como "a ignorar" (link em inglês).
Isso foi possível por meio de uma alteração em angular-cli
, criando um plug-in que se conecta ao módulo Compiler
do webpack (link em inglês).
O plug-in webpack que nossos engenheiros criaram hooks no cenário PROCESS_ASSETS_STAGE_DEV_TOOLING
e 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 de 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. Seu esforço e colaboração foram essenciais, e agradecemos seu esforço. Agradeço, equipe do Angular, por tornar isso possível.