Your Next.js Build Is Slow. Here's Where to Look First

Before you start

You just ran npm run build and it took four minutes. Your CI is red because the build timed out. Where do you even start? This guide walks through the most common culprits and shows you how to measure, fix, and verify each one.

You will need a Next.js project (version 12 or later) and Node.js installed. All commands are run from the project root.

npm run build

• Ensure you have a package.json with next and react installed.
• Run npm run build once to get a baseline.
• Have a terminal open for running commands.
• You will edit next.config.js and some pages.

Step 1: Measure your bundle sizes

The first thing to check is how large your JavaScript bundles are. Use the built-in analyzer to see which packages are eating up space.

Install the analyzer as a dev dependency and configure it in next.config.js.

npm install -D @next/bundle-analyzer

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // your existing Next.js config
});

• Run ANALYZE=true npm run build to generate the report.
• Open the HTML report in your browser.
• Look for packages over 100 KB that are imported in many pages.

Step 2: Eliminate duplicate dependencies

Large bundles often come from duplicate versions of the same library. Use a tool to detect them.

The following command lists all packages that are installed multiple times and shows their versions.

npx npm-dedupe --dry-run

• If you see duplicates, run npm dedupe to consolidate them.
• After deduping, rebuild and note the build time difference.
• Also consider using import maps or aliases to force a single version.

Step 3: Optimize images with next/image

Unoptimized images can slow down builds because Next.js processes them at build time. Use the next/image component to automatically optimize and lazy-load images.

Replace your img tags with next/image. Here is an example.

import Image from 'next/image';

<Image
  src="/hero.jpg"
  width={1200}
  height={600}
  alt="Hero image"
  priority
/>

• Set the width and height to avoid layout shift.
• Use priority for above-the-fold images to preload them.
• For remote images, configure domains in next.config.js.

Step 4: Leverage incremental static regeneration

If you have many static pages, generating them all at build time can be slow. Use Incremental Static Regeneration (ISR) to build pages on demand.

Add the revalidate option to getStaticProps to enable ISR.

export async function getStaticProps() {
  const data = await fetchData();
  return {
    props: { data },
    revalidate: 60, // seconds
  };
}

• This moves page generation out of the build step.
• Pages are generated on first request and then cached.
• Use ISR for pages that change occasionally, not for real-time data.

Step 5: Cache your build artifacts

Next.js caches build output automatically, but you can make it faster by persisting the cache across CI runs.

Add the following to your CI configuration (GitHub Actions example) to cache the .next folder.

- name: Cache Next.js build
  uses: actions/cache@v3
  with:
    path: |
      .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

• This speeds up subsequent builds by reusing cached compiled files.
• Make sure to invalidate the cache when dependencies change.
• You can also use a custom cache handler for more control.

Step 6: Analyze your build logs

Next.js outputs detailed build logs. Look for the slowest steps and any warnings about large chunks.

The following command will show you the build output with timing for each page.

npm run build 2>&1 | tee build.log

• Search for 'Compiled' and note the time for each route.
• Look for 'First Load JS' size and see if any page is above 200 KB.
• If a page is huge, consider code-splitting with dynamic imports.

Verify it worked

After applying the fixes, rebuild and compare the time. Also check the bundle sizes in the analyzer report.

Run the build again and observe the timing.

time npm run build

• Expect a reduction of 20-50% in build time.
• Confirm that the bundle sizes for your main pages have decreased.
• Run your test suite to ensure no functionality broke.

Troubleshooting

If your build is still slow, here are a few more things to check.

Sometimes the issue is not in your code but in the environment.

• Check your Node.js version; Next.js 14 requires Node 18.17 or later.
• If you are on Windows, consider using WSL for better performance.
• Make sure your CI runner has enough memory (at least 2 GB).
• If you use custom webpack config, ensure it is not adding extra processing.
• Consider using a build service like Vercel that optimizes builds automatically.

What I would do

Here is a recommended setup that combines all the above into a single next.config.js.

Start with this configuration and adjust as needed.

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  images: {
    domains: ['example.com'], // add your image domains
  },
  experimental: {
    optimizeCss: true,
  },
  swcMinify: true, // default in Next.js 13+
});

• Enable SWC minification for faster builds (default in Next.js 13).
• Use experimental.optimizeCss to remove unused CSS.
• Add your image domains to prevent runtime optimizations.
• Run ANALYZE=true npm run build to verify bundle sizes.

FAQ

• Q: Why is my build slow on CI but fast locally? A: CI often has less memory and no cache. Ensure you cache the .next folder and increase memory limits.
• Q: Does using TypeScript slow down the build? A: TypeScript type checking is optional; you can set typescript.ignoreBuildErrors to skip it, but it is not recommended.
• Q: Can I parallelize my build? A: Next.js builds pages in parallel by default, but you can also use a build server with multiple cores.
• Q: What is the best way to reduce bundle size? A: Use dynamic imports for heavy components, and remove unused dependencies.