# MUI Monorepo Architecture: A Complete Guide to the Material-UI Package Structure

> Explore the MUI monorepo architecture organizing Material-UI packages, tools, and docs in a single Yarn workspace for streamlined development and coordinated releases.

- Repository: [MUI/material-ui](https://github.com/mui/material-ui)
- Tags: architecture
- Published: 2026-02-26

---

**The MUI monorepo architecture organizes all Material-UI runtime packages, development tools, and documentation into a single Yarn Berry workspace repository, enabling coordinated releases and shared TypeScript tooling across `@mui/material`, `@mui/system`, and `@mui/base`.**

The `mui/material-ui` repository on GitHub implements a sophisticated monorepo architecture that houses the entire MUI ecosystem. This unified structure allows the team to manage multiple npm packages—from low-level unstyled primitives to high-level data grids—within a single codebase, ensuring consistent versioning and shared development infrastructure.

## High-Level Directory Structure

The MUI monorepo follows a standard workspace layout where publishable code, documentation, and tooling reside at specific top-level paths:

```

/
├─ packages/                # All publishable npm packages

│   ├─ mui-base/           # Low-level, unstyled components & hooks

│   ├─ mui-material/       # The core component library (styled)

│   ├─ mui-system/         # Styling engine (styled, sx, theme utils)

│   ├─ mui-icons-material/ # Material Design SVG icons as React components

│   ├─ mui-lab/            # Experimental components (pre-release)

│   ├─ mui-x-data-grid/    # Advanced data-grid component

│   ├─ mui-x-date-pickers/ # Date & time pickers

│   ├─ mui-utils/          # Shared utility helpers

│   └─ mui-types/          # Shared TypeScript types

├─ docs/                    # Documentation website source

├─ examples/                # Live demo applications

├─ scripts/                 # Build, lint, and release scripts

├─ .github/                 # CI/CD configuration & issue templates

├─ .yarn/ / .yarnrc.yml     # Yarn Berry workspace configuration

├─ package.json             # Workspace root, defines workspaces & dev deps

└─ lerna.json (optional)   # Historical Lerna config for publishing

```

## Workspace Configuration and Package Management

The MUI monorepo architecture relies on **Yarn Berry (v3+)** workspaces defined in the root [`package.json`](https://github.com/mui/material-ui/blob/main/package.json). This configuration enables deterministic dependency resolution and Plug'n'Play (PnP) support.

Each folder under `packages/` represents a discrete npm package that receives independent versioning during release cycles. Shared development dependencies—including TypeScript, ESLint, and testing utilities—are hoisted to the root `node_modules`, eliminating duplication across workspaces.

The root [`package.json`](https://github.com/mui/material-ui/blob/main/package.json) explicitly declares workspace globs:

```json
{
  "workspaces": [
    "packages/*"
  ]
}

```

Reference: [root [`package.json`](https://github.com/mui/material-ui/blob/main/package.json)](https://github.com/mui/material-ui/blob/master/package.json)

## Core Package Architecture and Dependencies

The MUI monorepo implements a layered dependency model where foundational packages provide primitives, and higher-level packages consume them to deliver styled components.

| Package | Purpose | Depends on | Key Entry Point |
|---------|---------|------------|-----------------|
| **@mui/base** | Unstyled building blocks, low-level hooks | – | [`packages/base/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/base/src/index.ts) |
| **@mui/system** | Styling utilities (`styled`, `sx`, `ThemeProvider`) | `@mui/base`, `@mui/utils` | [`packages/system/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/system/src/index.ts) |
| **@mui/material** | Full-featured, styled components (Button, Dialog, etc.) | `@mui/system`, `@mui/base`, `@mui/utils` | [`packages/material/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/material/src/index.ts) |
| **@mui/icons-material** | SVG icons as React components | `@mui/material` (peer) | [`packages/icons-material/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/icons-material/src/index.ts) |
| **@mui/lab** | Experimental components that may graduate to `material` | `@mui/material`, `@mui/system` | [`packages/lab/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/lab/src/index.ts) |
| **@mui/x-data-grid**, **@mui/x-date-pickers** | High-end components (grid, pickers) | `@mui/material`, `@mui/system` | respective [`src/index.ts`](https://github.com/mui/material-ui/blob/main/src/index.ts) files |
| **@mui/utils** | Helpers (deepClone, ownerDocument, etc.) | – | [`packages/utils/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/utils/src/index.ts) |
| **@mui/types** | Shared TypeScript types used across packages | – | [`packages/types/src/index.ts`](https://github.com/mui/material-ui/blob/main/packages/types/src/index.ts) |

These inter-package dependencies are declared in each package's [`package.json`](https://github.com/mui/material-ui/blob/main/package.json). For example, the **material** package's `peerDependencies` include `@mui/system` and `@mui/base`:

[packages/material/package.json](https://github.com/mui/material-ui/blob/master/packages/material/package.json)

## Build Pipeline and Distribution

The MUI monorepo architecture employs a centralized build system that compiles TypeScript source into distributable formats for each package.

1. **TypeScript compilation** – Each package compiles to both **ESM** (`.js`) and **CommonJS** (`.cjs`) outputs under `dist/`.
2. **Rollup** bundles the source for distribution, generating minified builds for production.
3. **Storybook** (in `examples/`) validates component rendering across environments.
4. **CI** (GitHub Actions) runs lint, type-checking, unit tests (`jest`), and visual regression tests before a release.

Key script: [scripts/build.js](https://github.com/mui/material-ui/blob/master/scripts/build.js)

## Theming and Styling Flow

The MUI monorepo architecture separates styling concerns across `@mui/system` and `@mui/material` to provide both flexibility and convention.

- The **theme** object is defined in `@mui/material` and extended via `@mui/system`'s `createTheme`.
- The **styled engine** (`@mui/system/styled`) uses Emotion (default) or styled-components as a pluggable backend.
- Components consume the theme through React context (`ThemeProvider`).

Source: [packages/system/src/createTheme.tsx](https://github.com/mui/material-ui/blob/master/packages/system/src/createTheme.tsx)

### Extending the theme with a custom palette

```tsx
import { createTheme, ThemeProvider } from '@mui/material/styles';
import { CssBaseline, Typography } from '@mui/material';

const theme = createTheme({
  palette: {
    primary: {
      main: '#00695c',
    },
    secondary: {
      main: '#ff6f00',
    },
  },
});

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <Typography variant="h4" color="primary">
        Custom Theme Demo
      </Typography>
    </ThemeProvider>
  );
}

```

*Relevant source*: theme creation – [packages/material/src/styles/createTheme.ts](https://github.com/mui/material-ui/blob/master/packages/material/src/styles/createTheme.ts)

## Documentation and Examples Structure

The MUI monorepo architecture co-locates documentation and example applications with the source code to ensure consistency.

- Docs are a **Next.js** site located under `docs/`. Markdown files import components directly from the monorepo, ensuring that the docs always reflect the latest code.
- Example apps (`examples/`) showcase usage patterns and serve as integration tests.

Docs entry: [docs/pages/getting-started/installation.md](https://github.com/mui/material-ui/blob/master/docs/pages/getting-started/installation.md)

### Using experimental Lab components

The `packages/mui-lab/` directory contains components that are not yet stable but available for testing.

```tsx
import * as React from 'react';
import { LoadingButton } from '@mui/lab';
import SaveIcon from '@mui/icons-material/Save';

export default function SaveButton() {
  const [loading, setLoading] = React.useState(false);

  const handleClick = () => {
    setLoading(true);
    // Simulate async action
    setTimeout(() => setLoading(false), 2000);
  };

  return (
    <LoadingButton
      loading={loading}
      loadingPosition="start"
      startIcon={<SaveIcon />}
      variant="contained"
      onClick={handleClick}
    >
      Save
    </LoadingButton>
  );
}

```

*Relevant source*: Lab components – [packages/lab/src/LoadingButton/LoadingButton.tsx](https://github.com/mui/material-ui/blob/master/packages/lab/src/LoadingButton/LoadingButton.tsx)

## Summary

- The **MUI monorepo architecture** consolidates all packages, documentation, and tooling under the `mui/material-ui` repository using **Yarn Berry workspaces**.
- **Layered package dependencies** create a stable foundation: `@mui/base` provides unstyled primitives, `@mui/system` handles styling utilities, and `@mui/material` delivers fully styled components.
- The **build pipeline** in [`scripts/build.js`](https://github.com/mui/material-ui/blob/main/scripts/build.js) compiles TypeScript to both ESM and CommonJS formats, ensuring broad compatibility across bundlers.
- **Co-located documentation** in `docs/` and example applications in `examples/` guarantee that guides and sample code remain synchronized with the latest API changes.

## Frequently Asked Questions

### What is the difference between @mui/base and @mui/material?

**@mui/base** provides unstyled, accessible component primitives and low-level hooks without any default styling, allowing complete visual customization. **@mui/material** builds upon `@mui/base` and `@mui/system` to offer fully styled components that implement Google's Material Design specification, including default themes and CSS.

### How does the MUI monorepo handle package versioning?

The MUI monorepo architecture uses independent versioning for each package under `packages/`, coordinated through Yarn Berry workspaces and release scripts. While packages like `@mui/material` and `@mui/system` often release together to maintain compatibility, experimental packages in `@mui/lab` or premium X-series components follow separate release cadences defined in their respective [`package.json`](https://github.com/mui/material-ui/blob/main/package.json) files.

### What build outputs does the MUI monorepo generate?

Each package in the MUI monorepo compiles TypeScript source into multiple distribution formats: **ES modules** (`.js`) for modern bundlers, **CommonJS** (`.cjs`) for Node.js compatibility, and **TypeScript declarations** ([`.d.ts`](https://github.com/mui/material-ui/blob/main/.d.ts)). The [`scripts/build.js`](https://github.com/mui/material-ui/blob/main/scripts/build.js) orchestrator uses Rollup to generate these outputs and places them in each package's `dist/` directory before publishing to npm.

### Where are experimental MUI components located?

Experimental components that have not yet reached stable API status reside in the **`packages/mui-lab/`** directory and publish to the `@mui/lab` npm package. These components, such as `LoadingButton` or the legacy `Autocomplete` before its stable release, import from `@mui/material` and `@mui/system` but remain separate to allow API iteration without breaking changes in the core library.