I knew something was wrong the moment I loaded my Next.js app in the browser. The initial page took far too long to become interactive. As a developer, that made my eye twitch. After some digging, I discovered the culprit: an avalanche of JavaScript being sent over the network on first load. This is the story of how I diagnosed and fixed a tangled web of imports that was bloating my bundle, cutting 500KB–1MB of JavaScript from the initial load and drastically improving performance.

The Mystery of the Slow Page Load

My journey began with a simple observation: the first page load was sluggish. Navigations after that were fine (thanks to client-side routing), but that initial load felt like wading through mud. Users hitting our site for the first time were paying a heavy cost in load time. I fired up Chrome DevTools and looked at the Network panel. Sure enough, over a megabyte of JavaScript (uncompressed) was being transferred on that first page. That’s a lot of script for just loading a page UI.

Why does this matter so much? Well, JavaScript is expensive for browsers to handle. Unlike an image that the browser can just display after downloading, JS has to be parsed, compiled, and executed — an intensive process. In fact, byte for byte, JavaScript can be more taxing than images or CSS. So sending 500KB or 1MB of extra JavaScript (even if it’s compressed to maybe ~200KB over the wire) can significantly slow down how quickly the page becomes usable. I had to trim this fat.

Digging Deeper with Bundle Analysis

First step in solving this: figure out what exactly is in that huge JavaScript bundle. I suspected we were shipping code that wasn’t needed upfront, or maybe some library was pulling in the kitchen sink. To get a closer look, I turned to the Webpack Bundle Analyzer. Next.js makes it easy to use via the @next/bundle-analyzer plugin, which generates an interactive treemap of your bundles. This tool is amazing – it shows each file or module and how much space it takes in the bundle, so you can literally see the bloat.

After enabling the bundle analyzer and building the app, I opened the report. It was immediately clear something was off. One chunk stood out as gigantic – much larger than anything else. Inside it, I could see pieces of code that looked familiar (names of our internal modules) combined with things that definitely did not belong in the client bundle (Node-specific libraries, polyfills, etc.). This was a huge red flag that some server-side code was being bundled into the client-side JavaScript by mistake.

The image above is an example of a Webpack Bundle Analyzer treemap (from another project) highlighting a single library (lottie.js in this case) dominating the bundle size. In my app’s report, a similar huge rectangle represented our internal API module pulling in a lot of code, confirming that something was dragging way more code into the client bundle than it should. Identifying these large chunks visually was a crucial first step in diagnosing the issue.

But knowing which chunk is large is only half the battle. I needed to understand why it was so large. What was pulling in these server-side bits? Time to put on the detective hat and trace some dependencies.

Mapping the Dependency Spaghetti

To untangle this mystery, I reached for another tool: dependency-cruiser. This nifty utility can analyze your project and spit out a dependency graph – basically a map of which files import which other files. By visualizing the import graph, I hoped to find the path through which our client-side code was inadvertently dragging in heavy server-side modules.

Running dependency-cruiser on the codebase (with Graphviz to generate an SVG diagram) produced a sprawling map of our project. It looked intimidating at first (picture a bowl of spaghetti noodles – that’s a typical large app’s dependency graph!). But I zeroed in on the part of the graph around that suspicious large module from the bundle report. There it was: an “API” module that had connections to both client-side pages and server-side utilities. Aha!

In our case, we had a file in our code (let’s call it api.js in the services layer) that was being imported by a Next.js page for client-side use, but inside api.js there were also imports of Node-only libraries and server-side code. Essentially, we had mixed together client and server concerns in one module. This made Webpack include everything from that module in both the client and server bundles. No wonder the client bundle was enormous!

This kind of entanglement confused Webpack’s tree shaking. Normally, a bundler like Webpack can “shake out” unused code (a.k.a tree shaking, which is an optimization to drop dead code). But here, the code in api.js that was meant for the server wasn’t clearly unused – it was just not needed on the client. Webpack couldn’t easily tell which parts of api.js were safe to omit for the browser. In fact, according to a Next.js discussion, Webpack wasn’t sure if the server exports had side effects, so it kept them in the client bundle. In other words, our tangled imports prevented effective tree shaking.

I also learned that Next.js has some built-in smarts to drop code that’s exclusively used in server-only functions (like getServerSideProps). But that only works if you keep your imports clean. In one case, we had an import that we intended only for server use, but because we imported it at the top of a page file and didn’t actually use it inside getServerSideProps, Next.js “thought” it might be needed on the client too – and so it bundled it there. Little oversights like that were costing us precious kilobytes.

Tangled Imports in Action (and the Fix)

Let me illustrate the core issue with a simplified example. Imagine we have a service module that looks like this:

// Before: Combined module (client + server mixed together)

// file: services/api.js

import AWS from 'aws-sdk';  // Node-only, heavy library (~MBs)

import fetch from 'node-fetch';  // another server-side import

export async function fetchDataClient(id) {

// Client-side logic (e.g., call a public API or another endpoint)

return fetch(`/api/data?id=${id}`).then(res => res.json());

}

export async function fetchDataServer(id) {

// Server-side logic using AWS SDK (should not run in browser!)

const dynamo = new AWS.DynamoDB();

return await dynamo.getItem({ Key: { id: { S: String(id) } }, /* ... */ }).promise();

}

In the above “Before” scenario, we have an api.js that exports two functions: one meant for client use, one for server. The client-side code (e.g., a Next page or component) might do import { fetchDataClient } from 'services/api' and use it. Even if fetchDataServer is never called on the client, by importing the entire api.js module, all of it gets bundled. That means the heavy aws-sdk (which is large) and node-fetch polyfill are now part of the client bundle, even though the browser will never actually execute fetchDataServer. Webpack can’t safely tree-shake it out because it doesn’t know if fetchDataServer might be used or have side effects. This is exactly what happened to us.

The fix? We refactored and decomposed that module at the “service” level, separating the client and server parts into different files. For example:

// After: Separate modules for client and server logic

// file: services/api-client.js

export async function fetchDataClient(id) {

// (same implementation as before, no Node-specific imports here)

return fetch(`/api/data?id=${id}`).then(res => res.json());

}

// file: services/api-server.js

import AWS from 'aws-sdk';

export async function fetchDataServer(id) {

// (same implementation as before, Node-only code lives here)

const dynamo = new AWS.DynamoDB();

return await dynamo.getItem({ Key: { id: { S: String(id) } } }).promise();

}

// file: pages/index.js (Next.js page component or data fetching)

import { fetchDataClient } from '@/services/api-client';

export default function HomePage(props) {

// ... uses fetchDataClient for some client-side operation if needed

}

// If we need server-side data fetching on this page:

export async function getServerSideProps(context) {

const id = context.params.id;

// import server logic dynamically or within this function to avoid bundling it in client

const { fetchDataServer } = await import('@/services/api-server');

const data = await fetchDataServer(id);

return { props: { data } };

}

By splitting api.js into api-client.js and api-server.js, we ensure that client-side code only imports the client module, which has no heavy dependencies, and the server-side code can import the server module when needed (even dynamically, as shown above, to keep it out of the initial bundle). This clear separation immediately allowed Webpack/Next to exclude the AWS library from the client bundle entirely. The suggestion from the Next.js team was precisely this: mark server-only code as side-effect free or move it into separate files. We chose to separate files, which made the boundaries crystal clear.

We also went through other instances of cross-contamination. In a few places, we had utility files that did double duty (similar to the above). We refactored those so that anything that runs on the server (database calls, file system access, etc.) lived in files that are only imported in server-side contexts (like API routes or within getServerSideProps). Conversely, our components and client-side code would only import lightweight client utilities.

Another tweak was ensuring we don't have any unused imports that could confuse Next’s bundler. For example, if you import a module in a page but never use it in getServerSideProps or the component, Next might not realize it's meant to be server-only and will include it on the client. So we cleaned those up or moved those imports inside the server-only functions. By doing an import inside getServerSideProps, you signal to Next that this code is purely server side, and Next will strip it from the client bundle. This is a neat trick for cases where you can’t easily separate a file — just import it on the fly in the server function.

Throughout this refactoring, I constantly rebuilt and checked the bundle analyzer to see the impact. It was like watching a weight-loss progress chart for my app. Every unnecessary import I eliminated or isolated made the bundles a bit leaner. 🏋️

Results: Lighter, Faster, More Efficient

After all these changes, the difference was dramatic. Our initial JS payload shrank by ~500KB to 1MB (depending on the page). That’s half a megabyte (or more) less JavaScript that the browser has to download, parse, and execute on first load. In terms of real user impact, the initial load felt snappier. Time-to-interactive dropped noticeably (hundreds of milliseconds saved, at least, and more on slower networks/devices). We no longer see a long "spin" before the page responds. The latency improvement was especially apparent on mobile devices where CPU and network are slower – exactly where that fat bundle hurt the most.

Qualitatively, it felt like we went from a clunky, heavy app to a slim, responsive one. And all of this without removing any feature – we simply loaded the right code in the right place.

Another bonus: our build times improved a bit too, since there was less code to process in the client bundle and fewer gigantic chunks to optimize. It’s a win-win.

Beyond the specific numbers, the biggest outcome was confidence: now I know our app is delivering only the code it needs to, and nothing more, to the user’s browser. No secret passenger sneaking onto the client-side express train.

Lessons Learned

This debugging journey taught me a few important lessons that are worth sharing with any Next.js (or generally, React/webpack) developer facing performance issues:

Key Takeaways

With these practices, you can keep your Next.js application lean and fast, giving users a better experience. In my case, solving the tangled imports issue was a game-changer for performance. Now the initial load is quick, and I can confidently say my app isn’t shipping JavaScript that it doesn’t need. 🎉