Key takeaways when upgrading to Craft 5

With Craft 6 on the horizon, now is the perfect time to evaluate where your sites stand. If you’re still running Craft 4 (or, heaven forbid, Craft 3), Craft 5 represents a significant leap forward with a modernized control panel, enhanced content modeling, and an improved developer experience that makes the upgrade worthwhile.

But like any major version bump, the transition requires careful planning and execution. Having worked through numerous Craft upgrades over the years, we’ve learned that the key to success lies in preparation. Here are our key takeaways to ensure your Craft 5 upgrade goes smoothly.

1. Preparation is everything

The smoothest Craft 5 upgrades happen when you’ve done your homework first. This isn’t the time to wing it or hope for the best.

Your pre-upgrade checklist

Before you even think about running composer update, make sure you’ve covered these essentials:

• Your live site must be running the latest version of Craft 4; you can’t upgrade directly from Craft 3 to Craft 5.
• All plugins are updated to their latest Craft 4-compatible versions, and Craft 5-compatible versions are available.
• Your project is free of deprecation warnings after thorough testing on Craft 4.
• Your environments meet Craft 5’s minimum requirements of PHP 8.2, MySQL 8.0.17+, or PostgreSQL 13+.

Pro tip: Craft has a "Craft 5 Upgrade" utility that lists each of your plugins and whether a Craft 5-compatible version exists. Use this to identify any potential roadblocks early.

Plugin compatibility deserves special attention

Some plugins require more careful consideration than others. Freeform and Calendar, for example, often have more complex upgrade paths due to their deep integration with Craft’s core functionality. Make sure to:

• Check each plugin’s upgrade documentation specifically.
• Test these plugins thoroughly in your local environment.
• Plan for potential template updates or configuration changes.
• Consider reaching out to plugin developers if you encounter issues.

Read the docs and slow down

I've you’ve done an upgrade or two it’s easy to get carried away and run on autopilot. With Craft 5 though quite a bit changed and even the most vanilla of sites might have a quirk you need to be aware of. Following the docs forces you to slow down and ensure everything is completed in the correct order.

During complex upgrades, we often create multiple branches to deploy in sequence, ensuring plugins aren’t uninstalled until their content has been migrated. You don’t need to do this all in one go.

2. Nested Matrix blocks are a game-changer

One of the biggest improvements in Craft 5 is native support for nested Matrix blocks. Previously, creating nested content like slideshows required plugins like Neo or creative workarounds.

Now you can:

• Create nested entries instead of blocks within Matrix fields.
• Display content using cards, entry lists, or the classic blocks view.
• Remove plugin dependencies for nested content structures.

For agencies, this means simplified content modeling, a better client experience, and reduced maintenance overhead.

3. Enhanced security with Passkeys

Craft 5 introduces Passkey support, replacing traditional passwords with more secure and convenient authentication.

As an agency jumping between multiple client projects, authentication has always been a bit of a dance. Passkeys solve these headaches by providing faster sign-ins, enhanced security, and a better client experience without sacrificing usability.

Be sure to onboard your clients to passkeys so they can enjoy the benefits.

4. Performance improvements that actually scale

Craft 5 introduces Lazy Eager-Loading with the new .eagerly parameter. Instead of managing unwieldy .with parameters on complex sites, you can now use eager-loading on downstream element queries, and Craft handles the optimization automatically.

This means cleaner, more maintainable code that performs better as your site grows. Try not to skip the optimization step now; it’s much easier to put these in place during the calm than to rush adding them during a storm.

5. Post-upgrade cleanup tools

Craft 5.3+ introduces powerful consolidation commands:

• fields/auto-merge – Automatically discovers and merges functionally identical fields.
• fields/merge – Manually merge fields of the same type.
• entry-types/merge – Merge entry types and update their usage.

These are particularly useful on projects with many Matrix fields or legacy content structures that could be simplified. Just remember: these tools generate content migrations that must be committed and deployed to all environments.

The bottom line: Upgrade with confidence

Craft 5 represents a significant step forward, but success depends on preparation and understanding what’s changed. Pay special attention to complex plugins like Solspace Freeform and Calendar, test thoroughly, and take advantage of the new consolidation tools post-upgrade.

When you follow this systematic approach, you’ll unlock all the benefits of Craft 5’s improved features while avoiding the common pitfalls that derail upgrade projects.

---

Need help with your Craft 5 upgrade? Our team specializes in smooth, stress-free Craft upgrades and ongoing maintenance. Get in touch to talk through your project and how we can help keep you updated and secure.