Profile next build memory

[6peterlu]

Summary

My next build process uses more than 2GB ram and causes my cloud instance to OOM. I would like to profile it but I do not know the best way to do so to identify the packages that may be causing the issue.

If there are any next config flags I should try that would also be very helpful. Currently I have

  experimental: {
    esmExternals: false
  }

set, as well as setting parallel: false on the TerserPlugin, but it hasn't made a meaningful difference in the end behavior.

Additional information

My next.config.js:

/** @type {import('next').NextConfig} */
const path = require('path');
const TerserPlugin = require('terser-webpack-plugin');

const nextConfig = {
  productionBrowserSourceMaps: true,
  webpack: (
    config,
    {
      buildId,
      dev,
      isServer,
      defaultLoaders,
      nextRuntime,
      webpack
    }
  ) => {
    if (!dev && !isServer) {
      config.optimization.minimizer = [
        new TerserPlugin({
          parallel: false
        })
      ];
    }
    config.resolve.alias = {
      yjs: path.resolve(__dirname, 'node_modules/yjs'),
      ...config.resolve.alias
    };
    config.module.rules.push({
      test: /\.svg$/i,
      issuer: /\.[jt]sx?$/,
      use: ['@svgr/webpack']
    });
    return config;
  },
  experimental: {
    esmExternals: false
  }
};

module.exports = nextConfig;

Example

No response

[xabierlameiro]

First thing to settle is which process is dying, because next build is a tree and the two halves fail for different reasons and take different fixes.

The parent compiles. The static-generation workers render your pages. A parent that peaks during compilation and a worker that climbs page after page look identical from the outside (your instance OOMs) and have nothing to do with each other. Sample the whole process tree over the build, not just the total, and you'll see which curve is yours. If it's the workers, the number that matters is MB per page. If it's the parent, it's a single peak during compilation, and no amount of reducing page count helps.

Then the thing that will waste your time if nobody tells you: one build is not a measurement. I tried to A/B one option in a config like yours today, three runs per arm, alternating:

run	option off	option on
1	216 MB	422 MB
2	334 MB	331 MB
3	450 MB	463 MB

Run 1 says the option doubles peak memory. It doesn't. The spread inside a single arm is wider than the gap between arms, and there's a drift across runs that has nothing to do with the flag. Had I stopped at one run per arm I'd have posted a confident wrong answer. Alternate the arms, do at least three, and treat anything smaller than your within-arm spread as noise.

For actually naming the packages, since that's what you asked: heap snapshots of the compilation process, not the workers. Run the build with NODE_OPTIONS=--inspect, attach DevTools, and take a snapshot as the peak builds. That gives you module names and retained sizes, which is what you want when the suspicion is a specific dependency. It's tedious and it's the only thing I know of that answers the question directly on a webpack build.

One more thing worth checking on your version. In current Next, lib/worker.js deletes max-old-space-size from NODE_OPTIONS when it spawns an isolated-memory worker:

if (isolatedMemory) {
    delete nodeOptions['max-old-space-size'];
    delete nodeOptions['max_old_space_size'];
}

So the one flag every OOM guide tells you to raise never reaches the worker that runs out of memory. I don't know when that started and I can't confirm it applied to your version, so grep your own node_modules/next/dist/lib/worker.js for it. If it's there, raising --max-old-space-size was never doing anything for the worker half of your build, which would explain why nothing you tried moved the needle.

I package the tree sampling as next-leak:

npx next-leak build .

It reports the parent peak and the worker curve separately, and MB per page. Node 22+. It doesn't need output: "standalone" for the build path. Naming what's retained needs a Turbopack build with server sourcemaps, so on your webpack setup you'd get the curves and the split but not the package names, which is why I'd still reach for DevTools for that part.

Are the workers climbing per page, or is it a single peak while it compiles? That decides everything else.