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!

Use Ctrl + ← / → to navigate

First page

Last page

Back to Documentation Home