Understanding ES Modules vs CommonJS in Bundlers

The architectural divergence between static ECMAScript modules (ESM) and dynamic CommonJS (CJS) dictates how modern bundlers construct dependency graphs, optimize payloads, and schedule network requests. ESM’s compile-time resolution enables deterministic tree-shaking and parallel chunk loading, while CJS’s runtime evaluation forces synchronous execution and introduces interop overhead. This guide establishes the foundational mechanics of format normalization, serving as the primary reference for the broader JavaScript Build Pipeline & Module Resolution Fundamentals ecosystem.

Static Analysis vs Dynamic Resolution: AST Implications

Bundler performance is fundamentally constrained by how module formats are parsed into Abstract Syntax Trees (ASTs). ESM relies on static import and export declarations, enabling bundlers to construct a complete, acyclic dependency graph during the initial compilation phase. This static topology allows for aggressive dead-code elimination, import hoisting, and concurrent network scheduling.

Conversely, CJS require() is a synchronous function call evaluated at runtime. Because the dependency path can be computed dynamically (e.g., require(`./modules/${name}`)), bundlers must conservatively include all possible targets during graph construction. When a project mixes formats, bundlers inject normalization layers (__esModule flags, synthetic wrappers) that increase the AST payload by approximately 1–3 KB per module. Tree-shaking fails entirely on CJS dynamic exports (module.exports.foo = ...), resulting in guaranteed dead-code retention in production chunks.

Webpack 5 Chunk Graph Topology and Interop Wrappers

Webpack 5 reconciles mixed module formats through an internal interop system. When a CJS module is imported into an ESM boundary, Webpack generates __webpack_require__.n wrappers and attaches __esModule: true to the export object. While functional, these wrappers introduce runtime checks that delay module initialization and fragment chunk boundaries.

To enforce strict ESM resolution and prevent synchronous chunk waterfalls, configure Webpack with experiments.topLevelAwait and resolve.fullySpecified. fullySpecified: true requires every import to include the file extension explicitly, eliminating ambiguous fallback chains—but be aware that this breaks most existing node_modules imports, so it should be applied selectively to your own application code rather than globally.

// webpack.config.js
module.exports = {
  experiments: {
    topLevelAwait: true, // Enables native async boundaries without synthetic wrappers
  },
  resolve: {
    fullySpecified: false, // Keep false for broad node_modules compatibility
    mainFields: ['module', 'main'],
    conditionNames: ['import', 'module', 'require'],
  },
  optimization: {
    concatenateModules: true, // Scope hoisting for ESM
    usedExports: true,        // Enable tree-shaking markers
  },
};

When ESM resolution is correctly configured, Webpack’s chunk graph topology becomes strictly deterministic, allowing the runtime scheduler to prefetch and preload chunks in parallel. For a complete breakdown of how these configurations influence split points and runtime chunk loading, refer to the Webpack Chunk Generation Lifecycle Explained.

Vite 5+ Pre-Bundling and Dependency Optimization

Vite bypasses traditional bundling during development by leveraging native browser ESM support. However, the ecosystem remains heavily populated with legacy CJS packages. Vite’s optimizeDeps phase uses esbuild to pre-bundle dependencies, converting CJS to ESM on-the-fly and flattening nested node_modules into a single cached chunk per dependency.

Explicitly scope include and exclude arrays to control this pipeline and prevent unnecessary pre-bundling of packages that are already ESM or that contain native addons:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    mainFields: ['module', 'main'],
    conditions: ['import', 'module', 'browser'],
  },
  optimizeDeps: {
    include: ['lodash-es', 'date-fns'], // Force ESM pre-bundling for these deps
    exclude: ['sharp', 'canvas'],       // Skip native/CJS-heavy packages
  },
  build: {
    commonjsOptions: {
      transformMixedEsModules: true, // Handle files that mix require() and import
    },
  },
});

When migrating legacy monorepos, path mapping must align with the pre-bundled cache to avoid duplicate module resolution. Apply the routing strategies outlined in How to configure module resolution aliases in Vite to ensure consistent alias resolution across dev and production pipelines.

Chunk Deduplication and Measurable Trade-offs

Mixing ESM and CJS directly impacts bundle size, parse/compile latency, and Time to Interactive (TTI). The following metrics reflect typical production audits across Webpack 5 and Vite 5 builds:

CJS modules force synchronous evaluation, blocking parallel chunk loading and delaying TTI. ESM enables static import hoisting, allowing the browser to fetch multiple chunks concurrently. Mixed-format graphs introduce interop wrappers that increase AST payload and trigger duplicate module inclusion when both require and import reference the same package.

To prevent regression, enforce CI gating with automated bundle-size thresholds:

# .github/workflows/bundle-audit.yml
name: Bundle Size & Format Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx webpack --config webpack.config.prod.js --json=stats.json
      - name: Check Bundle Size & CJS Interop
        run: |
          SIZE=$(node -e "
            const s = require('./stats.json');
            const main = s.assets.find(a => a.name.includes('main'));
            console.log(main ? main.size : 0);
          ")
          if [ "$SIZE" -gt "350000" ]; then
            echo "::error::Production bundle exceeds 350KB threshold. Audit CJS dependencies."
            exit 1
          fi

For deeper analysis of how circular dependencies and mixed formats fragment the dependency graph, consult Vite Module Graph and Dependency Resolution.

Implementation Workflow: Auditing and Format Normalization

Transitioning to a strict ESM architecture requires systematic auditing and enforced normalization:

1. Audit package.json exports: Run npx publint to identify packages with malformed or missing exports fields. Prioritize upgrading dependencies that only expose main (CJS) without module or exports (ESM).
2. Enforce sideEffects: Add "sideEffects": false to your own package.json and verify third-party packages declare it accurately. This enables aggressive dead-code elimination during tree-shaking.
3. Implement strict plugin chains: Use @rollup/plugin-commonjs with transformMixedEsModules: true to safely convert legacy imports. In Webpack, avoid running @babel/plugin-transform-modules-commonjs on your application source—that would convert ESM back to CJS, defeating tree-shaking.
4. Validate post-migration:

   # Webpack
   npx webpack --config webpack.config.prod.js --profile --json=stats.json
   npx webpack-bundle-analyzer stats.json
   
   # Rollup/Vite
   npx vite build
   # Then open the visualizer via rollup-plugin-visualizer configured in vite.config.ts

5. CI enforcement: Integrate size-limit into your PR pipeline to block regressions. Configure thresholds per chunk type (vendor, app, async) to guarantee that interop overhead never exceeds 5% of total payload.

Migrating to a pure ESM pipeline eliminates runtime interop checks, unlocks deterministic tree-shaking, and reduces parse latency. Enforce strict resolution rules at the configuration level, validate with automated CI gates, and continuously audit dependency formats to maintain optimal bundle topology.