A JavaScript bundle is large enough to make the page feel slow

Why it matters

`one of your JavaScript bundles` is over half a megabyte compressed, several times what a well-built entry bundle costs. JavaScript is the most expensive thing a page can load, and not because of the bytes. An image of this size is decoded off the main thread; a script has to be parsed, compiled and executed on the one thread that also handles every tap and click. That is why an oversized bundle shows up as a page that renders and then ignores you for a second, rather than simply as a slow load. The usual causes are a whole UI or charting library imported for one component, a date library pulled in for a single format call, and no route splitting — so the visitor downloads the dashboard's code to read the landing page. Run your bundler's analyzer to see what is actually in there before changing anything; the largest entry is rarely the one people guess.

How ShipReady detects it

JavaScript bundles heavy enough to be the reason a page feels slow. SITE-scoped so the entry bundle shared by every crawled page is weighed once, and so the scan's whole script budget is a fixed number rather than a number multiplied by the crawl size.

Detection is deterministic. ShipReady reports this only when it observes the condition directly, and prefers to miss a real problem over inventing one. Rule version 1.0.0.

How to fix it

This is the prompt ShipReady puts in your report — written to be pasted straight into Cursor, Claude Code, or whichever assistant built the app.

A JavaScript bundle on your site is over half a megabyte COMPRESSED, which is what visitors actually download. Find out what is in it before changing anything — the largest dependency is rarely the one people guess.

MEASURE FIRST, with your bundler's own analyzer:
    npx vite-bundle-visualizer            # Vite
    ANALYZE=true npm run build            # Next.js, with @next/bundle-analyzer
    npx webpack-bundle-analyzer stats.json

THE THREE USUAL CAUSES, in the order they are usually worth fixing.
  • A whole library imported for one component. `import { Chart } from 'chart.js'` often pulls the entire package; check whether it ships an ES-module build that tree-shakes, and import the specific submodule if not.
  • A date or utility library. `moment` is ~70 KB gzipped and unmaintained — `date-fns` or the built-in `Intl.DateTimeFormat` replace most uses. Same for `lodash`: import `lodash/debounce`, not `lodash`.
  • No route splitting, so someone reading your landing page downloads the dashboard's code. Split on the route boundary with `React.lazy` and `Suspense`, dynamic `import()`, or your framework's own per-route chunking.

DEFER WHAT IS NOT NEEDED TO RENDER. Analytics, chat widgets and anything below the fold can load after the page is interactive rather than before it. A script that must exist but need not run early belongs behind a dynamic import triggered on interaction.

CHECK COMPRESSION IS ON while you are there. This finding already accounts for it — the number above is the compressed size — but confirm brotli is enabled at your edge, since it is typically 15-20% smaller than gzip for JavaScript.

ONE THING NOT TO DO: minifying harder will not fix this. The bundle is large because of what it CONTAINS, and minification is already applied by your production build. Removing a dependency beats compressing it.

Frequently asked questions

What does "A JavaScript bundle is large enough to make the page feel slow" mean?

`one of your JavaScript bundles` is over half a megabyte compressed, several times what a well-built entry bundle costs.

How serious is it?

ShipReady rates this medium. Fix soon. Meaningfully weakens a defence or degrades how the site works.

How do I fix it?

Paste the fix prompt on this page into Cursor, Claude Code or your AI editor. It is the same prompt ShipReady puts in your report.

Can I check my own site?

Yes — ShipReady scans up to ten pages of any public site for free and reports this alongside every other check. The free report lists every issue it finds and shows full evidence and a fix prompt for the critical and high-severity ones; medium and low findings are counted and unlock on Pro.

Related checks

• An image is large enough to be slowing the page downmedium
• Real visitors wait too long to see your main contentmedium
• The page is served without compressionmedium
• The page is slow to respond when people tap or clickmedium
• The page moves under people while it loadsmedium
• Build assets are served without cachinglow