# Tree shaking: how it really works

Tree shaking drops unused code only when modules are ESM and side-effect free. A test with esbuild: 145 bytes against 59.

> Page: https://ui.eneawork.it/blog/tree-shaking-come-funziona
> Markdown: https://ui.eneawork.it/blog/tree-shaking-come-funziona.md

*2026-11-01*

Il tree shaking elimina il codice esportato e mai importato: funziona sui moduli ESM e lascia stare tutto ciò che il bundler non può dimostrare privo di effetti collaterali. Nella nostra prova la differenza è 145 byte contro 59.

Fixture di quattro file compilata con esbuild 0.21.5 il 1 novembre 2026: senza il campo sideEffects nel package.json l'output è di 145 byte e contiene il modulo mai importato; con "sideEffects": false l'output scende a 59 byte e quel modulo sparisce. Stesso entry, stesso minify, stesso formato ESM. Il modulo espone una funzione che scrive su window, quindi il bundler lo tiene quando non può escluderlo. Il catalogo EneUI misura 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, letti da /api/stats il 1 novembre 2026. Riferimenti: documentazione esbuild, licenza MIT; MDN, CC BY-SA 2.5.

## Le tre condizioni

Se manca una delle tre, il bundler tiene il codice per sicurezza. Non è pigrizia: un modulo può registrare un custom element o toccare window appena viene importato.

## Riprodurre la prova

npx esbuild entry.js --bundle --minify --format=esm --outfile=out.js && wc -c out.js

Il comando richiede Node e npx, più un entry.js che importi un solo export. Aggiungi sideEffects: false nel package.json della libreria e rilancia: se il file cala, il modulo inutilizzato era tenuto per i suoi effetti.

## Cosa resta fuori

## Il limite da dichiarare

Il tree shaking non riduce il codice che usi davvero: se un componente importa l'intera libreria di icone, il peso resta. La differenza tra 145 e 59 byte si vede su un modulo, non su un'applicazione; sui progetti grandi il guadagno arriva dai pacchetti con export nominati e dal controllo di cosa finisce nel grafo.

## Dove continuare

Il catalogo EneUI indicizza 111.985 componenti, 12.808 icone e il record 3D carousel: un componente che importa l'intero set di icone non perde nulla al build. Per il singolo import che gonfia il bundle leggi un import che aumenta il bundle, per il costo di render il profiler di React, per il confronto misurato tra pacchetti alternative a MUI 2026.

## FAQ

### Tree shaking e minify sono la stessa cosa?

No. Il minify accorcia i nomi e toglie gli spazi, il tree shaking elimina le dichiarazioni mai usate prima della minificazione.

### Perché la mia libreria non perde peso?

Perché è CommonJS o perché il package.json non dichiara sideEffects: false. In entrambi i casi il bundler tiene il codice per sicurezza.

### sideEffects: false può rompere qualcosa?

Sì, se un modulo importato per il suo effetto viene scartato. In quel caso elenca i file con effetti in un array al posto di false.

### Il tree shaking funziona con il CSS?

No, i fogli di stile sono import per effetto. Per il CSS si usa un plugin che rimuove le regole non usate, con risultati parziali.

### Da dove arriva la differenza tra 145 e 59 byte?

Da un modulo esportato e mai importato. Con sideEffects: false sparisce, senza il campo il bundler lo tiene perché registra qualcosa su window.