Update: A reader pointed out that Next.js 16.4 shipped an official bundle analyzer with snapshot diffs and an AI optimizer skill. It's the right tool for finding why a route is heavy. route-bundle-size solves a different problem: it stops a route from growing in the first place. Since v0.3.0 the two work together, see The investigator below.
So, AI-assisted coding or vibe coding is a fact of life now, but I'd rather not tell you guys about yet another "AI slop". However, it can lead to some interesting results, and it happened to us.
In one PR, we got some changes that looked good at first glance, human review didn't notice any issues, but one of our checks on the PR did. One page could swell up by 153 KiB, while the new code was only 7 KiB. So, in this article I'll tell you guys how we implemented a size guard, and what issues we faced during development.
The standard tool
In the previous article, we made some significant improvements. Honestly, we make some speed improvements constantly, some smaller, some bigger, but it is a permanent process of improvement. Well, if you improve something, you really want to keep it improved. But sometimes we noticed some degradation in our dashboards.
After a couple of analyses, we found out that all the degradations were related to a growing bundle size. We decided to keep an eye on it and check how other people do it.
Usually people do it manually, or use nextjs-bundle-analysis, or something like that. It didn't fit for us: it only reads Pages Router routes, and we were planning to move to the App Router. There wasn't the right tool for us.
The workaround
Let's start with the bad news: Next.js removed the sizes, the First Load JS stat and the manifests. According to their statements, it wasn't showing actual sizes for webpack and Turbopack.
So, here is what we had: @next/bundle-analyzer, which worked only for webpack builds, and next experimental-analyze, which is only for human analysis. It was impossible to create any pipelines based on those libs.
Well, as soon as I understood that, I decided to check what sort of artifacts we have after the build. Several greps and cats, and — BOOM, I found route-bundle-stats.json. Routes, chunks, all the data I needed. There are no compressed sizes, and the file is not documented, but it is fine, we took the risk.
I implemented a small CLI tool with a budget, compression, report comparison, all we needed. No rocket science, a tool that solves our issues.
I'd like to share with you guys how it works in a few words.
We have just two commands inside:
-
measureparses the build artifacts, gets the list of chunks and compresses them; -
diffjust compares two measurement results, shows the difference, highlights the routes that reached the thresholds, and fails with an error if needed.
If something goes wrong, like a chunk doesn't exist or the format has changed, the tool tells you and fails with an error.
The baseline problem
Well, our first version worked as simply as possible, look:
- Run
route-bundle-sizein every preview, and keep artifacts in GitHub; - In a feature PR we run a comparison and create some report.
But it led to issues with what we were actually comparing.
Two broken parts:
- In main, artifact uploading required a successful e2e run;
- A PR is not rebased onto the latest main every time.
So, we are living in the real world: e2e runs can sometimes be red, and developers sometimes don't keep their branches updated.
Let's imagine that main moved ahead by several commits, and one of those commits reduced the bundle size. Your branch will have a failed check, but you didn't do anything wrong, you just didn't have those commits in your branch.
It is especially hard to explain in the new AI world, where all the guys try to code something, make some prototypes, or implement something that they have in mind. But they're a bit less experienced than developers. It is frustrating for them.
About the numbers: roughly half of the v1 failures were false positives. Branches in sync with main failed in 5.7% of checks, branches 20+ commits behind — in 43%.
Well, based on our experience, we decided to migrate to a merge-base flow. So, here is how it works now, 3 jobs:
- Get artifacts from the current build;
- Get artifacts for the merge-base commit. 2 options: we can get them from the action cache, or run a new build;
-
Run the
route-bundle-sizeCLI -> compare artifacts -> update summary.
The public GitHub Action does the same in one job, but it always rebuilds the merge base and has no cache.
So, let's move on to what we caught!
The catch
Well. What happened?
We had a PR with some obvious changes, and most of those changes were written by an agent. As part of the product feature, the agent extracted a new module and exported it through the barrel; it is one of the rules, because we are living with FSD architecture. So, 4 files got this import:
import { getCanvasImagesSource } from '@/shared/model/canvas'
In another PR, the style page redesign was merged into main. Updating the PR with main led to this:
And honestly, it was just a coincidence. Neither of those PRs did anything wrong, both changes were valid separately. But together — BOOM.
Next step: we asked the agent to read that report and find the problem. And honestly, agents are so good at that part of debugging.
It parsed the bundles, found that the barrel pulled engine code into the style pages, and fixed only 4 imports! Type-only imports stayed on the barrel, TypeScript erases them anyway. On review, we moved the module into its own slice, so the FSD rule is kept and the bundle stays light:
- import { getCanvasImagesSource } from '@/shared/model/canvas'
+ import { getCanvasImagesSource } from '@/shared/model/canvasImages'
How bundle size looked on each step:
What was wrong initially? Source maps showed that the same modules were shared between entry points, and some of them ended up in the bundle twice (I guess that's how resolving circular dependencies works).
So, without a bundle size guard, our application overall would have grown by 200 KiB. Of course, we would have noticed it from alerts, but it would have been in production for some time.
The wins
Now, we've just discussed one side of that bundle size check. Let's take a look at the second side.
Our new approach to watching the bundle helps us not only gate the bad changes, it also helps us notice the good ones.
I have a good example for you guys: for some time we had been living with 2 different versions of our UI, it was impossible to separate them properly, and of course it led to some degradations.
After a huge amount of work and several experiments, we moved to the new one, and after that we decided to remove the old UI parts and check what changed. We deleted 220 files and 19,354 lines of code: /projects lost a quarter of its first-load JS (-26%), and 22 routes got lighter.
Well, now we have good proof of our work and of how refactoring can influence user experience. Not only "features" make user experience better.
The investigator
route-bundle-size shows what happened, and next analyze shows why.
A pull request imports all of lodash on the home page. route-bundle-size fails the check: Bundle size budget exceeded for 1 route(s): / (limit +30 KiB or +10%).
With analyze: true, the same run attaches the official analyzer report for the merge base and the PR. Download it from the job summary, run npx serve <folder> and open the compare view.
The treemap shows the cause right away: lodash.js, added.
Fix it yourself, or let your AI agent do it with Vercel's next-bundle-optimizer skill.
Turning it on is one line:
- uses: bra31k/route-bundle-size@v0
with:
analyze: true
The package
After our journey, we decided to open-source our small CLI comparator.
Where it lives now:
Well, what is it? It is our internal CLI tool that we used for half a year, and we finally decided to share it.
Of course, there are some nuances: the format is not documented by Next.js; only first-load JS (I'm pretty sure for now it is more important, but it may not be enough for somebody more nerdy than me!); Per-route budgets arrived in 0.2.0 (budget.overrides, budget.maxSize).
So guys, thank you for your time! Please feel free to take a look at it, leave issues, test it! I hope it will be helpful!
How we measured: CI logs from that time have expired, so all numbers in the cases were rebuilt locally on the same commits with [email protected]. The share of false v1 failures is a statistical estimate from the GitHub API, because v1 logs were deleted.








Top comments (4)
153 KiB from 7 KiB of new code is the perfect example of why this has to be a gate and not a dashboard. A barrel export is a one line change, it looks fine in review, and nobody reads the import graph in a diff.
The baseline section was the most useful part for me. 43% failures on branches 20+ commits behind is exactly how a check like this ends up ignored, and merge-base is the right fix. Wish more posts shared the "v1 was half false positives" part honestly.
You mention it only tracks first-load JS for now. Have you seen regressions sneak in through lazy chunks instead? Like a modal or a dynamic import that suddenly pulls in half a library. That's the one I'd worry about next.
Thanks! I really appreciate it.
About regressions in lazy chunks: they don’t hurt the first load, but they can hurt INP, when a modal has to download half a library before it opens. The stats file only lists first-load chunks, so the tool can’t see them yet.
But it’s a good point to keep in mind!
the 5.7% false positives in sync versus 43% at 20+ commits behind is what sold me on the merge base flow. we ran a size budget against main only and devs stopped trusting the check after two bad weeks, they just hit rerun until it went green.
caching the merge base artifacts is the right call, rebuilding it per PR gets slow fast. we also set the budget per route instead of per app, otherwise one barrel export hides inside the headroom of the whole bundle.
since that stats file is undocumented, do you have a canary build that fails when Next changes the format?
Thanks! Same experience here: once a check cries wolf, people just rerun it until it’s green.
Per-route is how the tool works from day one, for exactly the reason you describe.
On the canary: yes. The repo has a weekly job that builds a fixture app on next@canary and runs the action twice, once clean (must stay green) and once with a planted regression (must go red). If Next changes the file shape, the parser fails and the job goes red, so we’d hear about it before a release.