This document details the physical organization of the MUI monorepo, explaining its directory layout, package categorization, and workspace dependency management using pnpm and Lerna.
The MUI repository is a monorepo managed with pnpm (v9.0.0) and Lerna.
package.json enforces pnpm usage via an only-allow preinstall script package.json6lerna run build) and managing releases package.json9-16workspace:^ or workspace:* protocol, ensuring that local changes are reflected across the monorepo without needing to publish to npm pnpm-lock.yaml83-100@mui/internal-code-infra) is used for advanced build and release tasks, such as code-infra build and code-infra publish package.json13 packages/mui-material/package.json28Sources: package.json1-16 pnpm-lock.yaml1-100 packages/mui-material/package.json28
The repository is organized into several key directories, each serving a specific role in the development lifecycle.
| Directory | Purpose | Key Contents |
|---|---|---|
packages/ | Publicly published npm packages. | @mui/material, @mui/system, @mui/utils, @mui/icons-material, @mui/codemod. |
packages-internal/ | Tooling and utilities used internally for builds and docs. | @mui/internal-scripts, @mui/internal-api-docs-builder, @mui/internal-markdown. |
docs/ | The Next.js-based documentation website. | Documentation pages, component demos, and API reference data docs/package.json2-3 |
test/ | Global testing infrastructure. | Visual regressions, bundle size snapshots, and E2E configurations test/package.json2-3 |
scripts/ | Repository-level maintenance scripts. | releaseChangelog.mjs, generateProptypes.ts, buildApiDocs. |
examples/ | Boilerplate projects for various frameworks. | material-ui-nextjs, material-ui-pigment-css-vite-ts. |
Sources: package.json1-77 docs/package.json1-3 test/package.json1-3
packages/ DirectoryThis directory contains the core products and foundation libraries. Most packages follow a standard structure where the src/ directory contains the source code, and the build/ directory (generated via code-infra build) is what gets published to npm packages/mui-material/package.json87-90
These are the primary UI libraries.
sx prop engine packages/mui-system/package.json2-5deepmerge and useId packages/mui-utils/package.json2-5 packages/mui-utils/package.json31jscodeshift packages/mui-codemod/package.json2-5 packages/mui-codemod/package.json35Sources: packages/mui-material/package.json1-130 packages/mui-lab/package.json1-103 packages/mui-icons-material/package.json1-88 packages/mui-system/package.json1-96 packages/mui-utils/package.json1-75 packages/mui-styled-engine/package.json1-76 packages/mui-codemod/package.json1-55
packages-internal/)Packages in this directory are not intended for public use and are marked as "private": true. They support the build pipeline and documentation generation.
PropTypes (typescript-to-proptypes) and generating documentation files for LLMs (generate-llms-txt) packages-internal/scripts/package.json2-15docs/package.json docs/package.json105Sources: packages-internal/scripts/package.json1-57 docs/package.json105
docs/)The docs/ directory is a large Next.js application docs/package.json74 It depends on almost every package in the monorepo to render live demos and documentation.
react-runner for live execution docs/package.json89pnpm docs:api package.json19 which triggers the buildApiDocs/index.ts script package.json20docs:llms:build package.json21docs:create-playground package.json30 docs/package.json14Sources: docs/package.json1-136 package.json19-38
test/)Testing is distributed between package-level unit tests and repository-level integration tests.
pnpm --workspace-root test:unit --project "*:@mui/material" packages/mui-material/package.json30test/regressions, using Vite and Playwright/Argos to catch UI changes package.json59-63 package.json68test/bundle-size, tracking the impact of changes on the library's footprint via size:snapshot package.json46-47test:e2e-website package.json57-58validateTypescriptDeclarations.mts ensures .d.ts files are correctly generated package.json73Sources: package.json46-73 test/package.json1-42 packages/mui-material/package.json30
MUI uses the publishConfig.directory pattern to manage how packages reference each other. While source code is in src/, the workspace links often resolve to the build/ folder of a dependency to ensure the development environment closely matches the published state.
publishConfig: Defines that the build/ subdirectory is the root for the npm package. This allows for a "flat" package structure where users can import from @mui/material/Button instead of @mui/material/build/Button packages/mui-material/package.json87-90exports: Maps subpaths to internal source files for better tree-shaking and module resolution packages/mui-material/package.json97-120peerDependencies: Most component packages list react, react-dom, and styling engines (like @emotion/react) as peer dependencies to avoid duplicate installations in consumer apps packages/mui-material/package.json64-71overrides: Used in the root pnpm-lock.yaml to force specific versions of deep dependencies (e.g., stylis or @types/node) across the entire workspace pnpm-lock.yaml31-41Sources: packages/mui-material/package.json64-71 packages/mui-material/package.json87-120 pnpm-lock.yaml31-100
Refresh this wiki