Bundle Analyzer | blade47/next.js Wiki | doc0

Public

Bundle Analyzer | blade47/next.js Wiki | doc0

module.exports =
  ({ enabled = true, logLevel, openAnalyzer, analyzerMode } = {}) =>
  (nextConfig = {}) => {
    if (!enabled) {
      return nextConfig
    }
    if (process.env.TURBOPACK) {
      console.warn(
        'The Next Bundle Analyzer is not compatible with Turbopack builds, no report will be generated.\n\n' +
          'Consider trying the new Turbopack analyzer via `next experimental-analyze`.\n\n' +
          'See https://nextjs.org/docs/app/guides/package-bundling for more information\n\n' +
          'To run this analysis pass the `--webpack` flag to `next build`'
      )
      return nextConfig
    }
 
    const extension = analyzerMode === 'json' ? '.json' : '.html'
 
    return Object.assign({}, nextConfig, {
      webpack(config, options) {
        const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
        config.plugins.push(
          new BundleAnalyzerPlugin({
            analyzerMode: analyzerMode || 'static',
            logLevel,
            openAnalyzer,
            reportFilename: !options.nextRuntime
              ? `./analyze/client${extension}`
              : `../${options.nextRuntime === 'nodejs' ? '../' : ''}analyze/${
                  options.nextRuntime
                }${extension}`,
          })
        )
 
        if (typeof nextConfig.webpack === 'function') {
          return nextConfig.webpack(config, options)
        }
        return config
      },
    })
  }

Option Name	Type	Purpose
`experimentalAnalyze`	`boolean`	Activates experimental analysis modes
`profile`	`boolean`	Enables React production profiling during analysis
`mangling`	`boolean`	Controls whether variable mangling is enabled (disabling triggers a debugging warning)
`port`	`number`	Specifies the network port for interactive reporting servers
`output`	`boolean`	Toggles output generation behavior
`experimentalAppOnly`	`boolean`	Restricts analysis strictly to the App Router `app/` directory

Interface Name	Fields / Properties	Purpose
`AnalyzeModule`	`ident: string`, `path: string`	Represents an individual compiled module identifier and its file path
`AnalyzeSource`	`parent_source_index: number \| null`, `path: string`	Represents a source file node in the hierarchy, referencing its parent index
`AnalyzeChunkPart`	`source_index: number`, `output_file_index: number`, `size: number`, `compressed_size: number`	Maps source file segments to output files with raw and compressed sizes
`AnalyzeOutputFile`	`filename: string`	Stores the target emission filename for a compiled chunk
`AnalyzeLayer`	`name: string`	Identifies compilation layers (e.g., server, client, edge)
`EdgesDataReference`	`offset: number`, `length: number`	Points to a binary offset range containing packed edge lists

export function getSpecialModuleType(
  analyzeData: AnalyzeData | undefined,
  sourceIndex: SourceIndex | null
): SpecialModule | null {
  if (!analyzeData || sourceIndex == null) return null
 
  const path = analyzeData.source(sourceIndex)?.path || ''
  if (path.endsWith('polyfill-module.js')) {
    return SpecialModule.POLYFILL_MODULE
  } else if (path.endsWith('polyfill-nomodule.js')) {
    return SpecialModule.POLYFILL_NOMODULE
  }
 
  return null
}

Interface / Enum Name	Key Fields / Members	Purpose
`LayoutRect`	`x: number`, `y: number`, `width: number`, `height: number`	Defines absolute 2D canvas positioning and dimensions for rendered rectangles
`LayoutNodeInfo`	`name: string`, `size: number`, `server?: boolean`, `client?: boolean`, `traced?: boolean`	Carries descriptive metrics and flags for inspection tooltips
`LayoutNode`	`rect: LayoutRect`, `type: 'file' \| 'directory' \| 'collapsed-directory'`, `specialModuleType: SpecialModule \| null`, `children?: LayoutNode[]`, `itemCount?: number`	Represents a fully positioned node in the treemap hierarchy
`SizeMode`	`Compressed = 'compressed'`, `Uncompressed = 'uncompressed'`	Controls whether layout sizing calculations rely on compressed or raw byte metrics

Design Choice	Benefit	Cost
Bottom-up metadata precomputation (`precomputeSourceMetadata`)	Avoids redundant recursive tree traversals during geometry calculation	Requires allocating parallel metadata arrays covering all source indices upfront
Height-based directory collapsing (`isCollapsed = rect.height < 30`)	Preserves visual readability and prevents rendering sub-pixel clutter in tight viewports	Hides individual file blocks, requiring alternative summary counts
Path folding for single-child directories	Reduces vertical breadcrumb depth and conserves screen space for deeply nested modules	Obfuscates intermediate directory segments whose path length stays under the 40-character threshold

File Type / Condition	Base / Processed Color Code	Meaning / Purpose
Polyfill Module (`POLYFILL_MODULE`, `POLYFILL_NOMODULE`)	`#5f707f`	Neutral slate for client/nomodule polyfill chunks
JavaScript (`js`)	`#4682b4` (client) / Darkened (server)	Steel blue designating JavaScript source bundles
CSS (`css`)	`#8b7d9e` (client) / Darkened (server)	Muted purple designating style assets
JSON (`json`)	`#297a3a` (client) / Darkened (server)	Green designating JSON configuration or data files
Asset (`asset`)	`#da2f35` (client) / Darkened (server)	Red designating static assets and binary files
Default / Fallback	`#9ca3af`	Gray-400 fallback for unclassified nodes

export function computeActiveEntries(
  modulesData: ModulesData,
  analyzeData: AnalyzeData
): ModuleIndex[] {
  const potentialEntryDependents = [
    'next/dist/esm/build/templates/pages.js',
    'next/dist/esm/build/templates/pages-api.js',
    'next/dist/esm/build/templates/pages-edge-api.js',
    'next/dist/esm/build/templates/edge-ssr.js',
    'next/dist/esm/build/templates/app-route.js',
    'next/dist/esm/build/templates/edge-app-route.js',
    'next/dist/esm/build/templates/app-page.js',
    'next/dist/esm/build/templates/edge-ssr-app.js',
    'next/dist/esm/build/templates/middleware.js',
    '[next]/entry/page-loader.ts',
  ]
  const potentialEntries = [
    'next/dist/client/app-next-turbopack.js',
    'next/dist/client/next-turbopack.js',
  ]
  // ...
}

PathPart Property	Type	Purpose
`segment`	`string`	The individual directory or file path token.
`isCommon`	`boolean`	True if the segment matches the previous path prefix.
`isLastCommon`	`boolean`	True for the final overlapping segment in the shared prefix.
`isPackageName`	`boolean`	True if the segment forms part of a scoped or unscoped package name inside `node_modules`.
`isInfrastructure`	`boolean`	True if the segment resides within framework or package infrastructure paths.

Design Choice	Benefit	Cost
Recursive parent path concatenation (`getFullSourcePath`)	Reconstructs full nested module hierarchies cleanly without storing redundant absolute strings in memory.	Deep source hierarchies incur repeated pointer traversal overhead when resolving root paths.
Isolated chunk compression estimation (`getOwnSizes`)	Avoids expensive cross-module compression calculations during real-time sidebar rendering.	Estimated compressed sizes may diverge from actual final gzip chunk footprints.
String-based identifier splitting (`splitIdent`)	Extracts template arguments, layers, and tree-shaking metadata cleanly from complex Webpack/Turbopack identifiers.	Relies on strict regex formatting assumptions (`IDENT_ATTRIBUTES_REGEXP`) which fail on non-standard identifiers.

function SelectionDetails({
  analyzeData,
  modulesData,
  selectedSourceIndex,
  filterSource,
  moduleDepthMap,
  environmentFilter,
}: {
  analyzeData: AnalyzeData
  modulesData: ModulesData | null
  selectedSourceIndex: number
  moduleDepthMap: Map<number, number>
  environmentFilter: 'client' | 'server'
  filterSource: (sourceIndex: number) => boolean
}) {
  const specialModuleType = getSpecialModuleType(
    analyzeData,
    selectedSourceIndex
  )
 
  const selectedSource =
    selectedSourceIndex != null
      ? analyzeData.source(selectedSourceIndex)
      : undefined
 
  const hasChildModules =
    selectedSourceIndex != null &&
    analyzeData.sourceChildren(selectedSourceIndex).length > 0
 
  const { size, compressedSize } = analyzeData.getRecursiveSizes(
    selectedSourceIndex,
    filterSource
  )
  // ...
}