Upgrade Umbraco 13 to 16: introduction

#umbraco #webdev

It feels like only yesterday that the current LTS version of Umbraco (Umbraco 13) was released. Yet by the end of this year, it will already be celebrating its second birthday — and that can only mean one thing: time for a new Umbraco LTS version! At the end of the year, Umbraco 17 will arrive alongside .NET 10, which will also be an LTS release.

Version 13 will still receive security updates until December 2026, but feature updates, regression fixes, and compatibility tweaks? Those are done. So, if you haven’t already, it’s time to start thinking about your Umbraco 17 upgrade plan.

The biggest change in Umbraco 17 compared to 13 is, of course, the completely new bellissima backoffice, built with web components instead of AngularJS — first introduced in Umbraco 14. That release also brought us the Management API, giving full control over Umbraco through an API. In the same release, we waved goodbye to Nested Content and Macros (probably for the best 😉). Then Umbraco 15 introduced the HybridCache (replacing NuCache), block-level variants, and the shiny new TipTap rich text editor.

As of now, Umbraco 17 isn’t out yet — not even a release candidate — but I don’t expect it to be drastically different from Umbraco 16. Version 16 was more of an evolution than a revolution compared to 14 and 15, with a strong focus on stability and performance rather than big new features. I expect Umbraco 17 will follow the same approach.

In this blog series, I’ll go over some of the most common changes you’ll encounter when upgrading from Umbraco 13 to 16 (and, by extension, 17).

Over the next few weeks, I’ll cover the following topics based on my experiences upgrading both Umbraco projects and packages to versions 15 and 16 (this list will be updated with links as the posts go live):

First upgrade steps
Localization
Upgrading content delivery endpoints (previously UmbracoApiController)
Upgrading Management API controllers (previously UmbracoAuthorizedApiController)

I’ll only lightly touch on the new backoffice in these posts. This series isn’t meant to be an advanced guide to backoffice extensions, so I won’t be covering Lit, Vite, or TypeScript here — those deserve their own blog series in the future.