Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Performance and Patterns

Bundle Size and Imports

Keep a Material UI app small: path imports vs barrel imports, tree shaking, icon imports, code splitting with React.lazy, and how to analyze your bundle.

A UI library is code your users must download. Material UI is modular and tree-shakable, but a few habits can still make a bundle several times bigger than it needs to be, especially around icons and import style. Smaller bundles mean faster first loads, better Core Web Vitals and a lower bill for mobile users. This lesson covers where the weight comes from and the practical steps to cut it.

MUI cannot run in the live editors on this site. Real MUI imports are read-only. The runnable examples are stand-ins that model the cost of different import styles and the effect of lazy loading, so you can see why the advice works.

Where the weight comes from

Three things usually dominate a MUI app's JavaScript:

  1. The components you use and their dependencies: Emotion (the styling engine), @mui/system, @mui/utils and the Popper/transition helpers.
  2. Icons: @mui/icons-material has thousands of icons, one module each.
  3. Heavy add-ons: the Data Grid, date pickers, charts and rich editors, which are large on their own.

Your own code and other libraries add to it. Measure before guessing (see the analysis section below).

Import styles

You can import a component in two ways:

JSX
// Real Material UI, read-only
// 1. Path import: loads exactly one module
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';

// 2. Barrel import: loads the package's index file
import { Button, TextField } from '@mui/material';

With a modern bundler (Vite, webpack 5, Next.js, Rollup, esbuild) and production mode, both produce nearly the same bundle, because the packages declare "sideEffects": false and use ES modules, so unused exports are dropped. Differences show up in development: a barrel import makes the dev server resolve and transform thousands of modules, which slows startup and hot reload noticeably. For that reason, the MUI docs recommend path imports for the fastest development, and Next.js lists @mui/material and @mui/icons-material in its automatic optimizePackageImports.

Choose one style per project and enforce it with a lint rule, so the codebase stays consistent. A common restriction is no-restricted-imports for @mui/*/*/* (a third-level path import is private API and will break), while allowing the one-level path @mui/material/Button.

Never import from a second-level path such as @mui/material/Button/Button or from @mui/material/esm/.... Those are internal and can change in any release.

Try it: what the import style costs

This stand-in builds a small "package" of 40 modules, each with a size. A barrel import evaluates the whole index (all modules); a path import evaluates one. The bundler's tree shaking is simulated with a switch: with it on, only the modules you use remain in the final bundle, but the dev cost stays high because every module is still processed.

Barrel vs path imports: dev cost and bundle cost

Turn tree shaking off with the barrel style: this is what an old build setup or a CommonJS import does, and the whole library ships.

Icons

Icon packages are the classic trap. @mui/icons-material ships around 2,000 icons, each in its own file; a barrel import import { Menu, Search } from '@mui/icons-material' makes the dev server load them all (slow startup), though production builds drop the unused ones.

JSX
// Real Material UI, read-only
// Good: one file each
import MenuIcon from '@mui/icons-material/Menu';
import SearchIcon from '@mui/icons-material/Search';

// Avoid in development-heavy setups: loads the whole index
import { Menu, Search } from '@mui/icons-material';

Other options when you use many icons:

  • Create one icons module in your app that re-exports only the icons you use from path imports; import from it everywhere.
  • Use SvgIcon with your own SVG paths for the handful of custom icons.
  • For icons used on a landing page, inline the SVG; no JavaScript is needed.

Code splitting

Load rarely used, heavy parts only when needed. React.lazy with Suspense splits a component into its own chunk:

JSX
// Real Material UI, read-only
import { lazy, Suspense } from 'react';
import Skeleton from '@mui/material/Skeleton';

const DataGrid = lazy(() => import('./OrdersGrid')); // OrdersGrid imports @mui/x-data-grid

export function OrdersPage() {
  return (
    <Suspense fallback={<Skeleton variant="rectangular" height={420} />}>
      <DataGrid />
    </Suspense>
  );
}

Good candidates: the Data Grid, date pickers, charts, rich-text editors, big dialogs that most users never open, and whole routes (split by route first; it is the easiest and most effective).

Try it: lazy loading a heavy panel

React.lazy with a fallback skeleton

Analyze before optimizing

Look at the real numbers:

  • Vite: npx vite-bundle-visualizer or the rollup-plugin-visualizer plugin.
  • Next.js: @next/bundle-analyzer, enabled with ANALYZE=true.
  • webpack: webpack-bundle-analyzer.
  • Browser DevTools, Network tab: sort by size, look at the compressed (gzip or brotli) size, which is what travels over the wire.

Look for: one huge vendor chunk, an icon package that appears twice (different versions), duplicate copies of Emotion, and date libraries that arrive with a date picker (use only one adapter, for example dayjs). If two copies of @emotion/react exist, styles can also break; check npm ls @emotion/react.

A short checklist

  • Use path imports for components and icons, and enforce them with lint.
  • Split by route; lazy-load the Data Grid, pickers and editors.
  • Do not import the whole @mui/icons-material; make an icons module for frequently used ones.
  • Prefer sx or styled over importing extra styling libraries; there is no need for two CSS-in-JS systems.
  • Keep dependencies deduplicated (npm ls, npm dedupe).
  • Check the compressed size and set a budget in CI (for example with size-limit).
  • Measure again after each change.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a production build with a modern bundler, how do barrel and path imports of @mui/material differ?

    The packages are ES modules with sideEffects false, so unused exports are removed. In development, though, a barrel import makes the tooling process many more modules.
  2. 2. Why is a barrel import of @mui/icons-material especially slow in dev?

    Each icon is its own module. Importing the index forces the tooling to load them all.
  3. 3. Which part of an app is the best first candidate for code splitting?

    Route-level splitting and lazy loading of big optional components give the largest savings for the least work.
  4. 4. Which size should you watch when judging the cost of JavaScript on the network?

    What travels over the network is compressed, but the browser must still parse and run the uncompressed code.

Summary

  • The weight comes from components and Emotion, icons and big add-ons; measure first.
  • Path imports and barrel imports give similar production bundles, but path imports are faster in development.
  • Import icons from their own files, or create an icons module.
  • Split by route and lazy load heavy components with a Skeleton fallback.
  • Use a bundle analyzer and a size budget in CI.

Next: Rendering Performance and sx Cost