Skip to content

How Do I Make My JavaScript Bundle Smaller So My App Loads Faster?

6 min read

If your app feels slow on the very first visit, a large JavaScript bundle is one of the most likely causes. The short answer: find out what is actually in your bundle with an analyzer, then split it up so the browser only downloads the code each page needs, and load heavy libraries only when they are used. You rarely need to delete features. You need to stop shipping all of them at once.

Why this happens

When you asked your AI agent for a chart, a rich text editor, a date picker, and a PDF export, it added a library for each. Every one of those libraries is JavaScript the browser has to download, parse, and run before your page becomes usable. By default a lot of setups bundle everything into one big file, so a visitor who lands on your login screen still downloads the code for the chart they may never see.

The agent built exactly what you asked for and it worked in the demo, because on your laptop the file loads from disk in milliseconds. It never mentioned bundle size, because you did not ask, and nothing looked wrong. On a real phone over a mobile connection, that same file can take several seconds, and those seconds are the first impression your first users get.

How to check

  1. Look at the build output. After a production build (npm run build), most tools print a list of chunks and their sizes. Anything over a few hundred kilobytes for your main bundle is worth a closer look.

  2. Run a bundle analyzer to see what is inside. For a Vite app:

    npm install --save-dev rollup-plugin-visualizer

    Add it to your Vite config and build. It opens a treemap where the biggest boxes are your biggest offenders. Next.js has @next/bundle-analyzer for the same job.

  3. Check the network tab. Open your deployed site, open DevTools, go to the Network tab, tick "Disable cache", and reload. Sort by size. The large .js files at the top are what every first-time visitor pays for.

The fix

  1. Split by route. Load each page's code only when someone visits that page. In React this is React.lazy with Suspense; in Next.js and most modern frameworks, routing already does this if you let it. This alone often cuts the first download dramatically.
  2. Lazy-load heavy components. A charting library, a map, a rich text editor, or a PDF generator should load only when that feature appears on screen, using dynamic import(). The homepage should not carry the weight of the dashboard.
  3. Find the single biggest library and question it. The analyzer often shows one giant dependency doing a small job. A full date library for one date, a whole icon set for six icons, moment.js where a few lines would do. Replace or trim the worst one first.
  4. Import only what you use. import { debounce } from 'lodash' can pull in the entire library. Import the specific function or a per-function package instead, so the bundler can drop the rest.
  5. Rebuild and compare. Run the analyzer again and check the main chunk got smaller. Then reload the deployed site with the cache disabled and confirm the first load is lighter.

The trap to avoid

Do not reach for React.lazy on every tiny component and call it done. Splitting a 2 KB button into its own request makes things slower, not faster, because each request has its own overhead. Split the big, page-specific, and rarely-used things. Small shared pieces belong together. And splitting code does nothing for a page that is heavy for other reasons, so check your images too, since an unoptimised hero image often outweighs your entire script.

Where this fits

A heavy bundle is invisible on your laptop and painfully obvious on a real user's phone, which is exactly the kind of gap that separates "works on my machine" from "ready for people." It usually travels with other first-load issues, like huge images slowing down your site and a poor Lighthouse score you are not sure how to read. The free Readiness Report measures your real bundle and first-load time and tells you whether they are a problem for beta, and the Finishing Pass hands you the splits and swaps to make, in order.