Size Limit falha o CI quando o bundle JavaScript passa do orçamento

O que é o Size Limit

Size Limit é uma ferramenta de orçamento de performance para JavaScript, desenvolvida pela Evil Martians e hospedada no GitHub sob licença MIT, com cerca de 7 mil estrelas e 1,8 mil forks. Ela roda a cada commit no CI, calcula o custo real do JavaScript para o usuário final e lança um erro se o custo ultrapassar o limite definido - o que permite falhar o pipeline quando um pull request adiciona uma dependência pesada.

A ferramenta funciona com ES modules e tree-shaking, é modular e serve tanto para grandes aplicações com bundler próprio quanto para pequenas bibliotecas npm com muitos arquivos. Além do tamanho em bytes, ela pode calcular o tempo que um navegador levaria para baixar, compilar e executar o código - métrica considerada mais precisa e compreensível, já que navegadores demoram mais para processar 100 kB de JavaScript do que 100 kB de imagem. O plugin de tempo compara o desempenho da máquina atual com dispositivos Android de baixo custo para calcular a taxa de limitação de CPU e roda Chrome headless (ou desktop, se disponível) para medir a execução. Os cálculos incluem todas as dependências e polyfills. O projeto adverte que essas medições dependem dos recursos disponíveis e podem ser instáveis.

Como funciona e presets

O Size Limit é composto por uma CLI, plugins e presets. Os plugins incluem @size-limit/file (tamanho de arquivos com Brotli, Gzip ou sem compressão), @size-limit/webpack (empacota a biblioteca num projeto webpack vazio para rastrear dependências e polyfills), variações -why para relatórios de análise, @size-limit/esbuild, @size-limit/rolldown e @size-limit/time. Há três presets: preset-app (file + time, para aplicações com bundler próprio), preset-big-lib (webpack + file + time, para bibliotecas acima de 10 kB, como React) e preset-small-lib (rolldown + file, para bibliotecas abaixo de 10 kB, como Nano ID e Storeon, que medem só o tamanho). Plugins de terceiros nomeados com prefixo size-limit- também são suportados.

O fluxo típico: instalar o preset, adicionar a seção size-limit no package.json, rodar npm run size para obter o tamanho atual (por exemplo, 30,08 kB minificado e com Brotli), definir um limite com margem - a documentação sugere adicionar 25% ao total atual para apps, ou apenas cerca de um kilobyte para bibliotecas pequenas - e incluir o script size na suíte de testes.

Configuração, relatórios e análise

A configuração aceita a seção size-limit no package.json, arquivos .size-limit.json, .size-limit.js/.cjs ou .size-limit.ts. Cada seção suporta opções como path (obrigatória), import (para testar tree-shaking de exports específicos), limit (em B, kB, ms ou s), name, message, ignore, gzip/brotli, running, config personalizada e funções de modificação do bundler. Também é possível passar o limite direto pela CLI (npx size-limit --limit "10 kB" dist/bundle.js) ou usar --ignore-missing quando um workspace constrói apenas projetos alterados, e --config para apontar outro arquivo de configuração.

Com size-limit --why, a ferramenta analisa por que a biblioteca tem o tamanho atual, mostrando o custo de cada dependência interna por meio do Statoscope; o relatório é gerado como HTML e aberto no navegador, com nomes customizáveis por seção.

Um GitHub Action (andresz1/size-limit-action) comenta as mudanças de tamanho na discussão do pull request e rejeita o PR quando o limite é excedido; a configuração envolve um workflow em .github/workflows/size-limit.yml rodando em pull requests.

Adotaes notáveis

Entre os projetos que usam a ferramenta estão MobX, Material-UI, Ant Design e Autoprefixer. Casos documentados de redução: PostCSS e Browserslist reduziram 25% do tamanho, EmojiMart 20%, nanoid 33%, React Focus Lock 32% e Logux 90%.