Minimizing bundle size

Learn how to reduce your bundle size and improve development performance by avoiding costly import patterns.

Bundle size matters

Material UI's maintainers take bundle size very seriously. Size snapshots are taken on every commit for every package and critical parts of those packages. Combined with dangerJS, we can inspect detailed bundle size changes on every Pull Request.

Avoid barrel imports

Modern bundlers already tree-shake unused code in production builds, so you don't need to worry about it when using top-level imports. The real performance concern is during development, where barrel imports like @mui/material or @mui/icons-material can cause significantly slower startup and rebuild times.

// ✅ Preferred
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';

Instead of:

// ❌ Slower in dev
import { Button, TextField } from '@mui/material';

This is especially true when using @mui/icons-material, where named imports can be up to six times slower than default path-based imports:

// 🐌 Slower in dev
import { Delete } from '@mui/icons-material';

// 🚀 Faster in dev
import Delete from '@mui/icons-material/Delete';

This approach avoids loading unnecessary parts of the package and does not require any special configuration. It is also the default used in all our official examples and demos.

Enforce best practices with ESLint

To prevent accidental deep imports, you can use the no-restricted-imports rule in your ESLint configuration:

// .eslintrc
{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "patterns": [{ "regex": "^@mui/[^/]+$" }]
      }
    ]
  }
}

Avoid VS Code auto-importing from barrel files

To prevent VS Code from automatically importing from @mui/material, you can use the typescript.autoImportSpecifierExcludeRegexes in the VS Code project configuration:

// .vscode/settings.json
{
  "typescript.preferences.autoImportSpecifierExcludeRegexes": ["^@mui/[^/]+$"]
}

Using Next.js 13.5 or later?

If you're on Next.js 13.5 or newer, you're in good hands. These versions include automatic import optimization via the optimizePackageImports option. This removes the need for manual configuration or Babel plugins to optimize imports.