[POC] Improve TypeScript Theme Components Performance

[siriwatknp]

Important

Breaking Change for Type Imports: Deprecated type utilities (Components, ComponentsProps, ComponentsOverrides, ComponentsVariants, adaptV4Theme) have been moved to a new @mui/material/stylesDeprecated entry point. Users directly importing these types must update their imports.

🎯 Main Purpose

This PR resolves critical TypeScript compilation performance issues caused by circular type dependencies in the theme system. The previous Components<Omit<Theme, 'components'>> pattern triggered excessive type instantiations (~7xxk), leading to slow compilation, high memory usage, and degraded IDE performance.

🔧 Key Changes

Type System Refactoring

• Simplified Theme Components Type: Replaced complex Components<Omit<Theme, 'components'>> with a simple ThemeComponents interface
• New CreateThemeComponent Utility: Added generic type helper for type-safe component theme customization
• Performance Targets: Instantiations ~3xxK, Memory ~3xxMB

Code Organization

• New stylesDeprecated Directory: Moved deprecated APIs (Components, ComponentsProps, ComponentsOverrides, ComponentsVariants, adaptV4Theme) to packages/mui-material/src/stylesDeprecated/
• Updated Module Augmentation: Lab package now augments @mui/material/stylesDeprecated instead of @mui/material/styles

Performance Testing Infrastructure

• New perf-test Directory: Added TypeScript performance diagnostics tooling
• Comprehensive Testing Guide: README with instructions for running diagnostics, generating traces, and analyzing performance

📁 Files Affected

Core Type System (6 files)

• packages/mui-material/src/styles/createTheme.ts - Export new types
• packages/mui-material/src/styles/createThemeFoundation.ts - Add ThemeComponents interface
• packages/mui-material/src/styles/createThemeNoVars.d.ts - Add CreateThemeComponent type, simplify Theme interface
• packages/mui-material/src/styles/createThemeWithVars.d.ts - Remove redundant components from CssVarsThemeOptions
• packages/mui-material/src/styles/useThemeProps.d.ts - Use ThemeComponents instead of Components<>
• packages/mui-material/src/styles/index.d.ts - Remove deprecated exports, add new types

Deprecated Types Migration (6 files moved + 1 new)

Moved to stylesDeprecated/:

• adaptV4Theme.d.ts, adaptV4Theme.js, adaptV4Theme.test.js
• components.ts, overrides.ts, props.ts, variants.ts

New:

• packages/mui-material/src/stylesDeprecated/index.ts - Consolidated exports

Package Updates (5 files)

• packages/mui-lab/src/themeAugmentation/components.ts - Module path update
• packages/mui-lab/src/themeAugmentation/overrides.ts - Module path update
• packages/mui-lab/src/themeAugmentation/props.ts - Module path update
• packages/mui-docs/src/branding/brandingTheme.ts - Extend ThemeComponents with deprecated Components<>
• packages/mui-material/src/Button/Button.d.ts - Add ButtonTheme export

Internal Updates (2 files)

• packages/mui-material/src/DefaultPropsProvider/DefaultPropsProvider.tsx - Update import path
• packages/mui-material/src/locale/utils/LocaleTextApi.ts - Update import path

Performance Testing (3 new files)

• packages/mui-material/perf-test/README.md - Testing guide
• packages/mui-material/perf-test/test-createTheme.ts - Performance test case
• packages/mui-material/perf-test/tsconfig.json - Test configuration

🚀 Impact

Performance Improvements

• Reduced Type Instantiations: Eliminates circular dependency causing millions of redundant type instantiations
• Lower Memory Usage: Simplified types consume significantly less memory during compilation
• Faster IDE Experience: Type checking and autocomplete performance improvements

Migration Required

Users directly importing these types must update their imports:

// ❌ Old (no longer works)
import { Components, ComponentsProps } from '@mui/material/styles';

// ✅ New
import { Components, ComponentsProps } from '@mui/material/stylesDeprecated';

Module Augmentation Pattern

For packages extending MUI components (like @mui/lab):

// ❌ Old
declare module '@mui/material/styles' {
  interface Components extends LabComponents {}
}

// ✅ New
declare module '@mui/material/stylesDeprecated' {
  interface Components extends LabComponents {}
}

💡 Implementation Notes

New Component Theme Export Pattern

The Button component demonstrates the new pattern for exporting component-specific theme types:

// packages/mui-material/src/Button/Button.d.ts
export type ButtonTheme = {
  MuiButton: CreateThemeComponent<ButtonClassKey, ButtonProps>;
};

// Usage in consuming code:
declare module '@mui/material/styles' {
  interface ThemeComponents extends ButtonTheme {}
}

Performance Testing Workflow

cd packages/mui-material/perf-test

# 1. Run diagnostics
npx tsc --noEmit --diagnostics

# 2. Generate trace
npx tsc --noEmit --generateTrace trace-output --incremental false

# 3. Analyze
analyze-trace trace-output

Note

The performance testing infrastructure helps maintainers monitor TypeScript compilation metrics and identify performance regressions early.

🔍 Review Focus Areas

1. Type Safety: Verify CreateThemeComponent provides adequate type safety for component customization
2. Breaking Changes: Confirm migration path is clear for users importing deprecated types
3. Lab Compatibility: Test that Lab components still work correctly with new module augmentation
4. Performance: Run perf-test to validate instantiation counts are within targets
5. Documentation: Review README for clarity and completeness

Result

Metric	Baseline (ThemeOptions)	Fix	Improvement
Instantiations	747348	337500	54.9%
Memory used	553 MB	364879K	34.0%
Check time	4.43s	2.38s	46.3%
Total time	5.65s	3.29s	41.7%

Before:

Files:              815
Lines:           164674
Identifiers:     130208
Symbols:         377356
Types:           117528
Instantiations:  747348
Memory used:    553221K
I/O read:         0.15s
I/O write:        0.00s
Parse time:       1.02s
Bind time:        0.20s
Check time:       4.43s
Emit time:        0.00s
Total time:       5.65s

After:

Files:              355
Lines:           139531
Identifiers:     110988
Symbols:         258356
Types:            92894
Instantiations:  337500
Memory used:    364879K
I/O read:         0.08s
I/O write:        0.00s
Parse time:       0.73s
Bind time:        0.18s
Check time:       2.38s
Emit time:        0.00s
Total time:       3.29s

Test

Follow the packages/mui-material/perf-test/README.md to test this PR.

---

• I have followed (at least) the PR section of the contributing guide.

[mui-bot]

Netlify deploy preview

https://deploy-preview-47013--material-ui.netlify.app/

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	▼-906B(-0.17%)	▼-250B(-0.17%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 2652229