What is JavaScript Bundle Size?

What is JavaScript Bundle Size?

JavaScript bundle size is the total byte weight of all JavaScript files delivered to a user's browser for a given page or route. It's typically measured in kilobytes (KB) after gzip or Brotli compression.

Bundle size directly affects Time to Interactive (TTI), Interaction to Next Paint (INP), and Largest Contentful Paint (LCP) — three of Google's Core Web Vitals. Every kilobyte of JavaScript costs roughly 1ms of parse/compile time on a mid-range mobile device. So a 300 KB bundle can add 300ms+ of blocking time before a page becomes interactive.

The HTTP Archive's 2025 data shows the median mobile page ships ~500 KB of compressed JavaScript, up from ~450 KB in 2022.

Reducing bundle size is one of the highest-ROI performance wins. We've shipped this on 50+ projects and consistently see INP improvements of 30-50% when we cut JS payloads by half. A common first step is analyzing your bundle with tools like webpack-bundle-analyzer or @next/bundle-analyzer.

How it works

When you build a modern web app with a bundler like webpack, Vite, Turbopack, or esbuild, your source code and its node_modules dependencies get concatenated into one or more output files — bundles. The total size of these files is your bundle size.

There are two measurements that matter:

• Uncompressed size — what the browser actually parses and executes
• Transfer size — what crosses the network after gzip/Brotli compression (typically 60-80% smaller)

Both matter, but for different reasons. Transfer size affects download time. Uncompressed size affects parse and execution time on the main thread.

Here's how to check your Next.js bundle size:

# Install the analyzer
npm install @next/bundle-analyzer

# next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});
module.exports = withBundleAnalyzer({ /* your config */ });

# Run the analysis
ANALYZE=true npm run build

This generates a treemap visualization showing exactly which dependencies are eating your budget. Common offenders include moment.js (330 KB uncompressed — switch to date-fns or dayjs), full lodash imports (use lodash-es with tree-shaking), and icon libraries that ship thousands of SVGs.

Our preferred stack at Social Animal uses Next.js with Turbopack, which handles tree-shaking and code-splitting by default. But defaults aren't enough. You still have to audit what's actually ending up in the client bundle.

When to use it

Bundle size isn't something you "use" — it's something you monitor and manage. Here's when to prioritize it:

Actively optimize when:

• Your Lighthouse Performance score is below 80 on mobile
• INP exceeds the 200ms "good" threshold
• Your JS transfer size exceeds 150 KB per route
• You're shipping a SaaS product or e-commerce site where conversion depends on speed
• You've just added a new dependency and want to know its cost

Deprioritize when:

• You're building an internal tool where network conditions are controlled
• Your page is mostly static HTML with minimal JS (e.g., an Astro content site with zero client JS)
• You're pre-launch and still iterating rapidly on features — optimize once the API surface stabilizes

A useful rule of thumb: set a performance budget of 170 KB compressed JS per route. If you exceed it, investigate before shipping.

JavaScript Bundle Size vs alternatives

Bundle size is one of several performance metrics. Here's how it relates to adjacent concepts:

Bundle size is the root cause. Metrics like INP and TBT are the symptoms. Fix the cause and the symptoms improve.

Real-world example

On a recent Next.js 15 e-commerce project, our initial route bundle was 410 KB compressed. Lighthouse mobile score: 62. INP was 380ms on a Moto G Power.

We ran @next/bundle-analyzer and found three problems: a full chart.js import on the product page (it was only used on the dashboard), react-icons importing the entire icon set, and a date formatting library pulling in locale data for 40+ languages.

Fixes: dynamic import for chart.js behind the dashboard route, switched to @phosphor-icons/react with named imports, replaced the date library with Intl.DateTimeFormat. Total time: about 4 hours.

Result: bundle dropped to 145 KB compressed. Lighthouse hit 91. INP fell to 120ms. Conversion rate on mobile increased 14% over the following two weeks.