Material-UI v5 Migration - Executive Summary

Project: Allow2Automate
Date: 2025-12-22
Current Version: @material-ui/core@4.11.3
Target Version: @mui/material@5.15.0
Status: ✅ Ready to Execute

📋 Migration Overview

This is a comprehensive, executable migration plan to upgrade Material-UI from v4 to v5.

Time Estimate: 8-9 hours

⚡ Automated tasks: 30 minutes
🔧 Manual changes: 4.5 hours
🧪 Testing: 2 hours
🐛 Bug fixes: 1.5 hours

Files Affected: 12 components

🔴 High priority: 5 files (3.5 hours)
🟡 Medium priority: 2 files (45 minutes)
🟢 Low priority: 5 files (30 minutes)

🚀 Quick Start - Execute These Commands

1. Prepare Your Environment

cd /mnt/ai/automate/automate
git checkout -b mui-v5-migration
git stash  # Save any uncommitted changes

2. Run Automated Migration

# Make script executable (already done)
chmod +x scripts/mui-v5-migration.sh

# Execute automated migration
./scripts/mui-v5-migration.sh

This will:

✅ Create backups (git stash, package.json.backup)
✅ Uninstall old packages
✅ Install new packages + peer dependencies
✅ Run codemods
✅ Update import statements
✅ Generate manual change checklist

3. Manual Changes (Follow Priority Order)

Priority 1 Files (Fix These First):

# 1. app/app.js (15 min)
# 2. app/components/Login.js (45 min)
# 3. app/components/LoggedIn.js (60 min)
# 4. app/components/Pair.js (60 min)
# 5. app/components/PlugIns.js (45 min)

Refer to: scripts/mui-v5-manual-changes.md

4. Test & Verify

# Build
npm run build

# Lint
npm run lint

# Test
npm run test

# Run locally
npm run develop

5. Commit & Push

git add .
git commit -m "Migrate Material-UI v4 to v5

- Update dependencies (@material-ui/* → @mui/*)
- Add Emotion peer dependencies
- Run automated codemods
- Update component props and structure
- Fix breaking changes in Button, AppBar, TextField, Table
- Update all import paths

Resolves #[issue-number]"

git push origin mui-v5-migration

📦 Package Changes

Remove (old v4):

"@material-ui/core": "^4.11.3"
"@material-ui/icons": "^4.11.2"

Add (new v5):

"@mui/material": "^5.15.0"
"@mui/icons-material": "^5.15.0"
"@emotion/react": "^11.11.0"
"@emotion/styled": "^11.11.0"

Why Emotion? MUI v5 replaced JSS with Emotion for styling.

🔥 Breaking Changes Summary

Top 5 Breaking Changes (By Frequency):

Button label prop removed (4 occurrences)
- Old: <Button label="Text" />
- New: <Button>Text</Button>
AppBar completely restructured (3 occurrences)
- Old: <AppBar title="..." iconElementLeft={...} />
- New: Use Toolbar composition pattern
Table components renamed (3 occurrences)
- TableHeader → TableHead
- TableHeaderColumn → TableCell
- TableRowColumn → TableCell
TextField props renamed (2 occurrences)
- floatingLabelText → label
- hintText → placeholder
Tabs onChange signature changed (1 occurrence)
- Old: (element, value) => {}
- New: (event, value) => {}

Total Breaking Changes: 14 across 5 files

📁 Critical Files & Changes Required

1. app/app.js (15 min) - LOW RISK

// Change import
import { ThemeProvider } from '@mui/material/styles';
// Was: import { ThemeProvider as MuiThemeProvider } from '@material-ui/core/styles';

2. app/components/Login.js (45 min) - MEDIUM RISK

TextField: floatingLabelText → label, hintText → placeholder
AppBar: Complete restructure to Toolbar pattern
Button: Remove label prop
Fix Person icon import

3. app/components/LoggedIn.js (60 min) - HIGH RISK

Table: Complete restructure
AppBar: Toolbar pattern
Tabs: Update onChange signature
Button: Remove label prop
Fix icon imports

4. app/components/Pair.js (60 min) - HIGH RISK

LinearProgress: mode → variant
AppBar: Complete restructure
Table: Verify structure (partially updated)
Button: Remove label prop

5. app/components/PlugIns.js (45 min) - MEDIUM RISK

Button: Remove label prop
Table: Already updated, verify completeness
IconButton: Check color props

🧪 Testing Strategy

Component Testing (After Each Fix):

# Start dev server
npm run develop

# Test component in browser
# Check console for errors
# Verify visual appearance
# Test interactions

Integration Testing:

✅ Login flow (email → password → login button)
✅ Navigation (page transitions)
✅ Plugin management (install/delete/toggle)
✅ Device pairing (modal → selection → pairing)

Regression Testing:

✅ All existing features work
✅ No console errors
✅ No styling regressions
✅ Performance acceptable

🔄 Automated Codemods

The migration script runs these automatically:

npx @mui/codemod@latest v5.0.0/preset-safe app/
npx @mui/codemod@latest v5.0.0/theme-breakpoints app/
npx @mui/codemod@latest v5.0.0/table-props app/
npx @mui/codemod@latest v5.0.0/button-props app/
npx @mui/codemod@latest v5.0.0/link-underline-hover app/

These handle ~60% of the migration work automatically.

🔙 Rollback Plan

If Critical Issues Occur:

# Option 1: Full rollback
git reset --hard HEAD
git stash pop
cp package.json.backup package.json
npm install

# Option 2: Package rollback only (keep code changes)
cp package.json.backup package.json
npm install

# Option 3: Revert specific files
git checkout HEAD -- app/components/Login.js

Rollback Triggers:

Build process completely broken
Critical functionality lost
More than 25% of tests failing
Unrecoverable runtime errors
Migration exceeds 16 hours

📊 Progress Tracking

Use this checklist to track migration progress:

PHASE 1 - PREPARATION (10 min)
[ ] Create migration branch
[ ] Stash uncommitted changes
[ ] Review migration plan

PHASE 2 - AUTOMATED (30 min)
[ ] Run migration script
[ ] Verify package installation
[ ] Check codemod execution
[ ] Review import updates

PHASE 3 - MANUAL CHANGES (4.5 hrs)
Priority 1:
[ ] app.js (15 min)
[ ] Login.js (45 min)
[ ] LoggedIn.js (60 min)
[ ] Pair.js (60 min)
[ ] PlugIns.js (45 min)

Priority 2:
[ ] AddPlugin.js (30 min)
[ ] Checkbox.js (15 min)

Priority 3:
[ ] Verify container files (30 min)

PHASE 4 - TESTING (2 hrs)
[ ] Build succeeds
[ ] Linter passes
[ ] Unit tests pass
[ ] Component testing
[ ] Integration testing
[ ] Manual testing

PHASE 5 - FINALIZATION (1 hr)
[ ] Fix any bugs found
[ ] Code review
[ ] Update documentation
[ ] Create PR
[ ] Merge to master

📚 Documentation Files

All documentation is in /scripts/:

mui-v5-migration.sh - Main executable script
mui-v5-manual-changes.md - Detailed manual changes
mui-v5-component-checklist.md - Component-by-component guide
mui-v5-quick-reference.md - Quick reference
MIGRATION_README.md - Getting started guide

🎯 Success Criteria

Migration complete when:

✅ All 12 components render without errors
✅ Build process succeeds
✅ Linter passes (no MUI-related errors)
✅ All tests pass
✅ No console errors or warnings
✅ Login flow works end-to-end
✅ Plugin management works
✅ Device pairing works
✅ Visual appearance matches v4
✅ No performance degradation
✅ Code review approved

💾 Migration Data Stored

Migration plan stored in memory database:

npx claude-flow@alpha hooks memory-get --key "swarm/mui-migration/execution-plan"

Location: /mnt/ai/automate/automate/.swarm/memory.db

🔗 Additional Resources

MUI v5 Docs: https://mui.com/material-ui/
Migration Guide: https://mui.com/material-ui/migration/migration-v4/
Breaking Changes: https://mui.com/material-ui/migration/migration-v4/#breaking-changes
Component API: https://mui.com/material-ui/api/
Codemods: https://github.com/mui/material-ui/tree/master/packages/mui-codemod

⚠️ Important Notes

Backups are automatic - Script creates git stash and package backups
Test incrementally - Fix one component, test, then move to next
Codemods aren't perfect - They handle ~60%, manual work needed
Emotion is required - Don't skip peer dependencies
Icon imports may break - Some icon names changed
Table selection works differently - May need custom logic
AppBar is most complex change - Budget extra time
Button label prop is most common - Affects 4 files
Build will fail initially - Expected, manual fixes resolve it
Keep v4 docs open - Useful for comparison

🚦 Ready to Start?

Your next command:

./scripts/mui-v5-migration.sh

After automated script completes, follow scripts/mui-v5-manual-changes.md for manual fixes.

Good luck with the migration! 🚀

For questions or issues, the migration data is stored in memory and can be retrieved with claude-flow hooks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Material-UI v5 Migration - Executive Summary

📋 Migration Overview

Time Estimate: 8-9 hours

Files Affected: 12 components

🚀 Quick Start - Execute These Commands

1. Prepare Your Environment

2. Run Automated Migration

3. Manual Changes (Follow Priority Order)

4. Test & Verify

5. Commit & Push

📦 Package Changes

Remove (old v4):

Add (new v5):

🔥 Breaking Changes Summary

Top 5 Breaking Changes (By Frequency):

📁 Critical Files & Changes Required

1. app/app.js (15 min) - LOW RISK

2. app/components/Login.js (45 min) - MEDIUM RISK

3. app/components/LoggedIn.js (60 min) - HIGH RISK

4. app/components/Pair.js (60 min) - HIGH RISK

5. app/components/PlugIns.js (45 min) - MEDIUM RISK

🧪 Testing Strategy

Component Testing (After Each Fix):

Integration Testing:

Regression Testing:

🔄 Automated Codemods

🔙 Rollback Plan

If Critical Issues Occur:

Rollback Triggers:

📊 Progress Tracking

📚 Documentation Files

🎯 Success Criteria

💾 Migration Data Stored

🔗 Additional Resources

⚠️ Important Notes

🚦 Ready to Start?

FilesExpand file tree

MUI_V5_MIGRATION_PLAN.md

Latest commit

History

MUI_V5_MIGRATION_PLAN.md

File metadata and controls

Material-UI v5 Migration - Executive Summary

📋 Migration Overview

Time Estimate: 8-9 hours

Files Affected: 12 components

🚀 Quick Start - Execute These Commands

1. Prepare Your Environment

2. Run Automated Migration

3. Manual Changes (Follow Priority Order)

4. Test & Verify

5. Commit & Push

📦 Package Changes

Remove (old v4):

Add (new v5):

🔥 Breaking Changes Summary

Top 5 Breaking Changes (By Frequency):

📁 Critical Files & Changes Required

1. app/app.js (15 min) - LOW RISK

2. app/components/Login.js (45 min) - MEDIUM RISK

3. app/components/LoggedIn.js (60 min) - HIGH RISK

4. app/components/Pair.js (60 min) - HIGH RISK

5. app/components/PlugIns.js (45 min) - MEDIUM RISK

🧪 Testing Strategy

Component Testing (After Each Fix):

Integration Testing:

Regression Testing:

🔄 Automated Codemods

🔙 Rollback Plan

If Critical Issues Occur:

Rollback Triggers:

📊 Progress Tracking

📚 Documentation Files

🎯 Success Criteria

💾 Migration Data Stored

🔗 Additional Resources

⚠️ Important Notes

🚦 Ready to Start?