Keeping Three.js out of your main bundle
How an ESLint rule, lazy registry chunks and a per-route budget script keep Three.js, PixiJS and MapLibre off the pages that do not need them.
· Updated · 4 min read

Three things keep a heavy graphics engine out of the pages that do not use it: a lint rule that forbids the import, a registry that loads each experiment as its own lazy chunk, and a script that fails the build when a page downloads code it should not. Each one covers a gap the others leave open.
This site has dozens of interactive demos that use Three.js, PixiJS, MapLibre, Cesium and other engines. The home page and the tools never ship any of them.
1. A lint rule forbids the import#
The first line of defence is ESLint's no-restricted-imports. It lists the heavy packages and allows them only inside two folders:
const heavyEngines = ["three", "three/*", "@react-three/*", "pixi.js", "pixi.js/*", "maplibre-gl", "cannon-es" /* ... */];
{
files: ["src/**/*.{ts,tsx}"],
ignores: ["src/experiments/**", "src/scenes/**"],
rules: {
"no-restricted-imports": ["error", { patterns: [{ group: heavyEngines, message: "Heavy engines are only allowed inside src/experiments/** ..." }] }],
},
}
Anyone who imports three from a shared component gets an error in the editor, long before the bundle grows. The list covers more than I use today, so a new engine is blocked by default if its package is on it.
2. Each experiment is a lazy chunk#
An experiment is loaded through a registry, one line per example:
"amber-vial": dynamic(() => import("./amber-vial"), { ssr: false, loading: () => null }),
next/dynamic with ssr: false makes each entry its own chunk, fetched only on its page. The page around it, with its title, text and loader, is static HTML.
The lint rule alone is not enough, because a chunk can still end up shared. If two components import the same module and one of them is on a content page, the bundler can put the module into a chunk that the content page loads. Only a measurement catches that.
3. A script that loads every route#
npm run budgets builds on a simple idea: open each page in a real browser, add up what it downloads, and fail if it is too heavy. The script loads each route in a hand-written list (the home page, the tools, the topic pages and every experiment) in a Pixel 7 profile, scrolls to the bottom so lazy chunks load, sums the gzipped JavaScript and compares it with a budget.
The budgets are in kilobytes of gzip:
| Page type | Budget |
|---|---|
| Content page (home, topic pages, tools) | 350 KB |
| Experiment page | 700 KB |
| Map page | 700 KB |
One route has its own limit, the Cesium example, because that engine alone is about 1 MB gzipped.
Markers catch leaks#
The second job of the script is to find code in the wrong place. Each experiment owns a unique marker string, like NEON_STRIP_MARKER_7c41, that exists in its own chunk. After a page loads, the script reads every downloaded file and looks for markers.
- The page's own marker must be present. If it is missing, the route is not loading its experiment.
- No other marker may be present. If any page downloads a chunk that contains another experiment's marker, that is a leak, and the run fails.
The markers are read from the route list, so every listed experiment is checked. A new experiment still has to be added to that list.
The budgets moved#
The numbers above are not the ones I started with. The content budget was 190 KB after the first set of animation libraries landed, then 240 KB, then 350 KB during a redesign phase where I chose visual impact first and planned to trim later. Experiment and map pages went to 700 KB when I decided richer scenes were worth the weight. Each change is recorded with its reason in the project's status file.
A budget you raise whenever it fails is only a log. What keeps it useful here is that every raise is a written decision, and that the leak check does not move at all. A leak check fails the run regardless of the size budget.
At one point the script reported the home page at 192.1 KB against a 190 KB budget, while I was working on an unrelated example. That is the kind of drift the budget exists to show.
Keeping the engine out of the bundle is one half; the other is what the visitor sees while an example's chunk loads, which I covered in A WebGL loading screen before JavaScript. The Lab cards follow the same rule with media: hover video previews fetch their clip only when someone points at a card.
Blind spots in the check#
The sizes in the budgets are gzip at level 9, measured by my script, and not what a real CDN sends. I have not compared them with field data. There is a second check besides the markers: a list of ten engine signatures (three, React Three Fiber, PixiJS, p5, Rive, Phaser, MapLibre, Leaflet, deck.gl and Cesium) that fails any content page whose downloaded code matches one. It only knows those ten, so a leak of cannon-es, satellite.js or Spine's runtime would pass.