Migration Guide

Step-by-step guide for migrating from deprecated components to new unified components

Component Migration Guide#

This guide helps you migrate from deprecated components to their new unified counterparts while maintaining backward compatibility.

Backward Compatible

All deprecated components still work! Migrate at your own pace. This guide helps you take advantage of improved performance and new features.

Quick Migration Matrix#

Deprecated Component	New Component	Variant	Effort
`MetricsCard`	`UnifiedMetrics`	`variant="default"`	Easy
`MetricsGrid`	`UnifiedMetrics`	`variant="card"`	Easy
`StatsGrid`	`UnifiedMetrics`	`variant="minimal"`	Easy
`StatsOverview`	`UnifiedMetrics`	Custom	Medium
`InfoBox`	`UnifiedInfo`	`variant="alert"`	Easy
`InfoCard`	`UnifiedInfo`	`variant="card"`	Easy
`InfoSection`	`UnifiedInfo`	`variant="section"`	Easy
`InfoGrid`	`UnifiedInfo`	`variant="grid"`	Medium
`InfoItem`	`UnifiedInfo`	`variant="item"`	Easy

Metrics Components Migration#

MetricsCard → UnifiedMetrics#

Old:

Mdx

<MetricsCard
  title="Performance Metrics"
  metrics={[
    { label: "Users", value: "10K" },
    { label: "Revenue", value: "$1M" }
  ]}
  layout="grid"
/>

New:

Mdx

<UnifiedMetrics
  title="Performance Metrics"
  variant="default"
  metrics={[
    { label: "Users", value: "10K" },
    { label: "Revenue", value: "$1M" }
  ]}
  layout="grid"
/>

Changes:

✅ Add variant="default"
✅ Everything else stays the same
✅ Fully backward compatible

MetricsGrid → UnifiedMetrics#

Old:

Mdx

<MetricsGrid
  title="KPIs"
  metrics={[...]}
  columns={3}
  showTrends={true}
/>

New:

Mdx

<UnifiedMetrics
  title="KPIs"
  variant="card"
  metrics={[...]}
  columns={3}
  showTrends={true}
/>

Changes:

✅ Add variant="card"
✅ All props work identically

StatsGrid → UnifiedMetrics#

Old:

Mdx

<StatsGrid
  stats={[
    { label: "Total", value: "100" },
    { label: "Active", value: "50" }
  ]}
  columns={3}
  size="md"
/>

New:

Mdx

<UnifiedMetrics
  metrics={[
    { label: "Total", value: "100" },
    { label: "Active", value: "50" }
  ]}
  columns={3}
  size="md"
  variant="minimal"
/>

Changes:

✅ Rename stats → metrics
✅ Add variant="minimal"

StatsOverview → Custom UnifiedMetrics#

Old:

Mdx

<StatsOverview />

New:

Mdx

<div className="my-8 p-6 bg-gradient-to-r from-blue-50 to-indigo-50 dark:from-blue-900/20 dark:to-indigo-900/20 rounded-lg border">
  <h2 className="text-2xl font-bold mb-4 text-center">Professional Overview</h2>
  <UnifiedMetrics
    metrics={[
      { label: "Years Experience", value: "10+", color: "blue" },
      { label: "Technologies", value: "25+", color: "green" },
      { label: "Projects", value: "50+", color: "purple" }
    ]}
    columns={3}
    variant="minimal"
  />
</div>

Changes:

ℹ️ This was a preset component
✅ Replace with custom layout + UnifiedMetrics
✅ Customize values for your data

Info Components Migration#

InfoBox → UnifiedInfo#

Old:

Mdx

<InfoBox type="info" title="Important">
  This is an information box
</InfoBox>

New:

Mdx

<UnifiedInfo type="info" variant="alert" title="Important">
  This is an information box
</UnifiedInfo>

Changes:

✅ Add variant="alert"
✅ Everything else identical

InfoCard → UnifiedInfo#

Old:

Mdx

<InfoCard title="Feature" description="Details about feature">
  Additional content
</InfoCard>

New:

Mdx

<UnifiedInfo variant="card" title="Feature">
  Details about feature
  
  Additional content
</UnifiedInfo>

Changes:

✅ Add variant="card"
✅ Move description to content
✅ Combine all content in children

InfoSection → UnifiedInfo#

Old:

Mdx

<InfoSection color="blue" title="Section Title">
  Section content here
</InfoSection>

New:

Mdx

<UnifiedInfo variant="section" color="blue" title="Section Title">
  Section content here
</UnifiedInfo>

Changes:

✅ Add variant="section"
✅ Props work identically

InfoGrid + InfoItem → UnifiedInfo#

Old:

Mdx

<InfoGrid columns={3}>
  <InfoItem icon="🚀" title="Fast">
    Lightning fast performance
  </InfoItem>
  <InfoItem icon="🔒" title="Secure">
    Enterprise security
  </InfoItem>
  <InfoItem icon="📈" title="Scalable">
    Auto-scaling infrastructure
  </InfoItem>
</InfoGrid>

New:

Mdx

<UnifiedInfo variant="grid" columns={3}>
  <UnifiedInfo variant="item" icon="🚀" title="Fast">
    Lightning fast performance
  </UnifiedInfo>
  <UnifiedInfo variant="item" icon="🔒" title="Secure">
    Enterprise security
  </UnifiedInfo>
  <UnifiedInfo variant="item" icon="📈" title="Scalable">
    Auto-scaling infrastructure
  </UnifiedInfo>
</UnifiedInfo>

Changes:

✅ InfoGrid → UnifiedInfo variant="grid"
✅ InfoItem → UnifiedInfo variant="item"
✅ All props work the same

Automated Migration#

Find & Replace Script#

Save this as migrate-components.sh:

Bash

#!/bin/bash

echo "🔄 Migrating components..."

# Metrics components
find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<MetricsCard/<MetricsCard variant="default"/g' {} \;

find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<MetricsGrid/<MetricsGrid variant="card"/g' {} \;

find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<StatsGrid/<StatsGrid variant="minimal"/g' {} \;

find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/stats={/metrics={/g' {} \;

# Info components
find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<InfoBox/<InfoBox variant="alert"/g' {} \;

find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<InfoCard/<InfoCard variant="card"/g' {} \;

find content/ -type f -name "*.mdx" -exec sed -i '' \
  's/<InfoSection/<InfoSection variant="section"/g' {} \;

echo "✅ Migration complete!"
echo "📝 Please manually review InfoGrid -> UnifiedInfo grid migrations"

Usage:

Bash

chmod +x migrate-components.sh
./migrate-components.sh

Manual Migration Steps#

Step 1: Backup Your Content#

Bash

# Create a backup
cp -r content/ content-backup/

Step 2: Update One Component Type at a Time#

Start with the easiest:

InfoBox → UnifiedInfo
MetricsCard → UnifiedMetrics
MetricsGrid → UnifiedMetrics
InfoCard → UnifiedInfo
More complex migrations last

Step 3: Test After Each Change#

Bash

npm run dev
# Check pages with migrated components

Step 4: Commit Frequently#

Bash

git add content/
git commit -m "Migrate MetricsCard to UnifiedMetrics"

Common Migration Issues#

Issue 1: Missing Variant Prop#

Error:

Component renders incorrectly, looks different than before

Solution:

Mdx

<!-- Add the correct variant prop -->
<UnifiedMetrics variant="card" ... />
<UnifiedInfo variant="alert" ... />

Issue 2: Wrong Prop Names#

Error:

TypeScript error: Property 'stats' does not exist

Solution:

Mdx

<!-- Change stats → metrics -->
<UnifiedMetrics
  metrics={[...]}  <!-- not stats -->
/>

Issue 3: Nested InfoGrid#

Old:

Mdx

<InfoGrid columns={2}>
  <InfoItem>Item 1</InfoItem>
  <InfoGrid columns={2}>
    <InfoItem>Nested 1</InfoItem>
    <InfoItem>Nested 2</InfoItem>
  </InfoGrid>
</InfoGrid>

Solution: Flatten or restructure:

Mdx

<UnifiedInfo variant="grid" columns={2}>
  <UnifiedInfo variant="item">Item 1</UnifiedInfo>
  <div>
    <UnifiedInfo variant="grid" columns={2}>
      <UnifiedInfo variant="item">Nested 1</UnifiedInfo>
      <UnifiedInfo variant="item">Nested 2</UnifiedInfo>
    </UnifiedInfo>
  </div>
</UnifiedInfo>

Benefits of Migration#

Performance#

Component	Before	After	Improvement
Metrics (all 4)	~8KB	~2.5KB	69% smaller
Info (all 5)	~7KB	~1.8KB	74% smaller
Total	~15KB	~4.3KB	71% reduction

Maintainability#

✅ One component to maintain instead of multiple
✅ Consistent API across all variants
✅ Easier to add new features
✅ Better TypeScript support
✅ Unified documentation

Features#

New features available in unified components:

✅ Enhanced SEO with keywords and JSON-LD
✅ Better dark mode support
✅ Improved accessibility
✅ More flexible styling options
✅ Performance optimizations

Migration Timeline#

Immediate (Do Now)#

✅ Review this guide
✅ Backup your content
✅ Run automated script

This Week#

✅ Migrate MetricsCard and MetricsGrid
✅ Migrate InfoBox and InfoCard
✅ Test in development

This Month#

✅ Migrate remaining components
✅ Update custom implementations
✅ Complete testing
✅ Deploy to production

Testing Checklist#

After migration, verify:

Visual Testing#

Functional Testing#

Performance Testing#

Page load time improved or same
Bundle size reduced
No console errors
Memory usage stable

Rollback Plan#

If issues occur:

Quick Rollback#

Bash

# Restore from backup
rm -rf content/
cp -r content-backup/ content/
npm run build

Gradual Rollback#

Bash

# Revert specific files
git checkout HEAD~1 -- content/docs/specific-file.mdx

Keep Both Versions#

The deprecated components still work! You can:

Keep using old components
Migrate gradually
Mix old and new components

Need Help?#

Stuck on Migration?#

Check Component Documentation
Review Component Playground
See API Reference
Check error messages carefully

Report Issues#

If you find migration issues:

Document the error
Note which component
Share your MDX code
Include screenshots

Migration Success Stories#

Case Study: Documentation Site

Before Migration:

15 MDX files with metrics
Bundle size: 245KB
4 different metric components

After Migration:

Same 15 MDX files
Bundle size: 178KB (27% reduction)
1 unified component

Time to Migrate: 2 hours

Next Steps#

After successful migration:

✅ Remove content-backup/ folder
✅ Update team documentation
✅ Share migration experience
✅ Monitor performance metrics
✅ Enjoy improved maintainability!

Migration Guide

Component Migration Guide#

Backward Compatible

Quick Migration Matrix#

Metrics Components Migration#

MetricsCard → UnifiedMetrics#

MetricsGrid → UnifiedMetrics#

StatsGrid → UnifiedMetrics#

StatsOverview → Custom UnifiedMetrics#

Info Components Migration#

InfoBox → UnifiedInfo#

InfoCard → UnifiedInfo#

InfoSection → UnifiedInfo#

InfoGrid + InfoItem → UnifiedInfo#

Automated Migration#

Find & Replace Script#

Manual Migration Steps#

Step 1: Backup Your Content#

Step 2: Update One Component Type at a Time#

Step 3: Test After Each Change#

Step 4: Commit Frequently#

Common Migration Issues#

Issue 1: Missing Variant Prop#

Issue 2: Wrong Prop Names#

Issue 3: Nested InfoGrid#

Benefits of Migration#

Performance#

Maintainability#

Features#

Migration Timeline#

Immediate (Do Now)#

This Week#

This Month#

Testing Checklist#

Visual Testing#

Functional Testing#

Performance Testing#

Rollback Plan#

Quick Rollback#

Gradual Rollback#

Keep Both Versions#

Need Help?#

Stuck on Migration?#

Report Issues#

Migration Success Stories#

Case Study: Documentation Site

Next Steps#

Related Resources#