Skip to main content
The performance configuration provides hints when assets or entry points exceed specific file size limits. This helps you keep bundle sizes under control.

​
Basic Configuration

webpack.config.js
module.exports = {
  performance: {
    hints: 'warning',
    maxAssetSize: 250000,
    maxEntrypointSize: 250000
  }
};

​
Performance Options

​
performance
object | false
Configure performance hints or disable them.
performance: {
  hints: 'warning',
  maxAssetSize: 250000,
  maxEntrypointSize: 250000
}
// or disable
performance: false
​
performance.hints
false | 'error' | 'warning'
Control how performance hints are displayed.
performance: {
  hints: 'warning' // Show warnings
  // or
  hints: 'error'   // Fail build on exceeded limits
  // or
  hints: false     // Disable hints
}
Default: 'warning' in production, false in development
​
performance.maxAssetSize
number
Maximum size (in bytes) for individual assets.
performance: {
  maxAssetSize: 250000 // 250 KB
}
Default: 250000 (244 KiB)Files exceeding this limit will trigger a warning/error.
​
performance.maxEntrypointSize
number
Maximum size (in bytes) for entry point assets.
performance: {
  maxEntrypointSize: 250000 // 250 KB
}
Default: 250000 (244 KiB)The combined size of all assets for an entry point that exceed this limit will trigger a warning/error.
​
performance.assetFilter
function
Filter which assets should be considered for performance hints.
performance: {
  assetFilter: function(assetFilename) {
    // Only consider JS and CSS files
    return /\.(js|css)$/.test(assetFilename);
  }
}
Default: Only considers assets ending with .js or .css

​
Understanding Limits

​
Asset Size

Individual file size limit: 
performance: {
  maxAssetSize: 200000 // 200 KB per file
}
This checks each emitted file (JS, CSS, images, etc.) that passes the assetFilter.

​
Entry Point Size

Total size of all assets for an entry point: 
performance: {
  maxEntrypointSize: 400000 // 400 KB total
}
This checks the combined size of all assets loaded by an entry point (main bundle + chunks + CSS).

​
Common Configurations

​
Development (Disabled)

webpack.dev.js
module.exports = {
  mode: 'development',
  performance: {
    hints: false // Disable in development
  }
};

​
Production (Warnings)

webpack.prod.js
module.exports = {
  mode: 'production',
  performance: {
    hints: 'warning',
    maxAssetSize: 250000,    // 244 KB
    maxEntrypointSize: 250000 // 244 KB
  }
};

​
Strict Production (Errors)

webpack.prod.js
module.exports = {
  mode: 'production',
  performance: {
    hints: 'error', // Fail build
    maxAssetSize: 200000,    // 195 KB
    maxEntrypointSize: 300000 // 293 KB
  }
};

​
Large Application

webpack.config.js
module.exports = {
  performance: {
    hints: 'warning',
    maxAssetSize: 500000,    // 500 KB
    maxEntrypointSize: 1000000 // 1 MB
  }
};

​
Custom Asset Filter

Only check JavaScript bundles:
webpack.config.js
module.exports = {
  performance: {
    hints: 'warning',
    maxAssetSize: 300000,
    assetFilter: function(assetFilename) {
      return assetFilename.endsWith('.js');
    }
  }
};
Exclude source maps and images:
webpack.config.js
module.exports = {
  performance: {
    hints: 'warning',
    assetFilter: function(assetFilename) {
      return !assetFilename.endsWith('.map') && 
             !/\.(png|jpg|jpeg|gif|svg)$/.test(assetFilename);
    }
  }
};

​
Size Units Reference

// Bytes
1024        // 1 KB
10240       // 10 KB
102400      // 100 KB

// Kilobytes
200 * 1024  // 200 KB
250 * 1024  // 250 KB (~244 KiB)
500 * 1024  // 500 KB

// Megabytes
1024 * 1024     // 1 MB
2 * 1024 * 1024 // 2 MB
Helper function: 
const KB = 1024;
const MB = 1024 * 1024;

module.exports = {
  performance: {
    maxAssetSize: 300 * KB,     // 300 KB
    maxEntrypointSize: 1 * MB   // 1 MB
  }
};

​
Environment-Based Configuration

webpack.config.js
module.exports = (env, argv) => {
  const isProduction = argv.mode === 'production';
  
  return {
    performance: isProduction ? {
      hints: 'error',
      maxAssetSize: 250000,
      maxEntrypointSize: 250000
    } : false
  };
};

​
Performance Budgets Strategy

​
Progressive Enhancement

Start strict and loosen if needed: 
performance: {
  hints: 'error',
  maxAssetSize: 200000,    // Start with 200 KB
  maxEntrypointSize: 300000 // Start with 300 KB
}

​
Different Budgets per Entry

Use multiple configurations:
webpack.config.js
module.exports = [
  {
    name: 'main-app',
    entry: './src/index.js',
    performance: {
      maxAssetSize: 300000,
      maxEntrypointSize: 500000
    }
  },
  {
    name: 'admin-app',
    entry: './src/admin.js',
    performance: {
      maxAssetSize: 200000,
      maxEntrypointSize: 400000
    }
  }
];

​
Best Practices

​
1. Set Realistic Limits

Based on your target users and network conditions: 
// Fast 3G target (~100 KB initial)
performance: {
  maxAssetSize: 100000,
  maxEntrypointSize: 200000
}

// Standard web app (~250 KB)
performance: {
  maxAssetSize: 250000,
  maxEntrypointSize: 500000
}

// Rich application (~500 KB)
performance: {
  maxAssetSize: 500000,
  maxEntrypointSize: 1000000
}
Track bundle size over time: 
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  performance: {
    hints: 'warning',
    maxAssetSize: 250000
  },
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      reportFilename: 'bundle-report.html'
    })
  ]
};

​
3. Code Splitting

Reduce entry point size: 
module.exports = {
  performance: {
    maxEntrypointSize: 250000
  },
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10
        }
      }
    }
  }
};

​
4. Tree Shaking

Remove unused code: 
module.exports = {
  mode: 'production',
  optimization: {
    usedExports: true,
    sideEffects: true
  },
  performance: {
    maxAssetSize: 200000
  }
};

​
5. Dynamic Imports

Lazy load features: 
// Instead of
import HeavyComponent from './HeavyComponent';

// Use dynamic import
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

​
Handling Warnings

When you see performance warnings: 
WARNING in asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).
This can impact web performance.
Assets: 
  main.js (350 KiB)

WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
Entrypoints:
  main (350 KiB)
    main.js

​
Solutions:

  1. Analyze the bundle: 
    npm install --save-dev webpack-bundle-analyzer
  2. Split chunks: 
    optimization: {
  splitChunks: { chunks: 'all' }
}
  3. Dynamic imports: 
    import('./module').then(module => { /* use module */ });
  4. Tree shaking: 
    import { specific } from 'library'; // Instead of import * as lib
  5. Compression: 
    const CompressionPlugin = require('compression-webpack-plugin');
plugins: [new CompressionPlugin()]
  6. Increase limits (last resort): 
    performance: {
  maxAssetSize: 500000
}

​
CI/CD Integration

Fail builds that exceed budgets:
webpack.prod.js
module.exports = {
  performance: {
    hints: process.env.CI ? 'error' : 'warning',
    maxAssetSize: 250000,
    maxEntrypointSize: 250000
  }
};
Package.json script: 
{
  "scripts": {
    "build": "webpack --config webpack.prod.js",
    "build:ci": "CI=true npm run build"
  }
}