Part 10: Best Practices - The Wisdom of Experience

Best practices are the scars of those who went before us.

The Do's

• ✅ Use @site/ imports everywhere
• ✅ Keep components pure
• ✅ Leverage MDX for documentation
• ✅ Test mobile first
• ✅ Use TypeScript
• ✅ Clear cache reflexively
• ✅ Version control before major changes
• ✅ Test production builds before deploying

The Don'ts

• ❌ Don't use preflight: true in Tailwind
• ❌ Don't put components in docs/
• ❌ Don't skip the Layout wrapper
• ❌ Don't use relative imports in pages
• ❌ Don't deploy without testing
• ❌ Don't modify node_modules
• ❌ Don't use React Router
• ❌ Don't ignore build warnings

Success Criteria

• ✅ All pages load without errors
• ✅ Styling is preserved
• ✅ Interactivity works
• ✅ Build succeeds with no errors
• ✅ Mobile responsive
• ✅ MDX works
• ✅ Deploys successfully

End of Series

The great migration is complete. Now ship it.

Read the full series: The Great Migration: Series Introduction