Umbraco 14 was released on the 30th of May 2024 and on first glance it might not feel like much has changed, however, prepared to be shocked 😱

Keep reading or watch the related video in order to learn all about this monumental release! In this guide, you will learn all about v14, how to install it, if you should upgrade to it, and more importantly what new goodies it ships with!

If you stumbled across this article because you were after a practical developers guide to get you up-to-speed with Umbraco v14, you are in the right place 🔥🔥🔥

How To Install Umbraco 14 For A New Project

First, lets start with how you can install the CMS. One good thing about installing Umbraco nowadays is that the install steps are pretty much the same for any release, so if you can skip this section if you know have this knowledge already.

First, v14 is compatible with .NET 8. So make sure you have Visual Studio patched to the latest version and you have .NET 8 installed (see here)

After doing this you need to install the Umbraco v14 installation template. You can do that within a terminal using this command:

With the Umbraco installation template installed, you can generate your website files using this command:

When the file installer finishes, it will create a new folder on your hard-disk. The folder name will match the project name you specified within your command. Within this new folder, you will find a project .csproj. Open this .csproj within Visual Studio to access your files and start building your site.

The final installation step is to install the CMS database. You can do this by either doing a dotnet run within the terminal (make sure to change to the project folder), or, within the Visual Studio UI by clicking the debug button. If everything goes OK, the Umbraco installation wizard should load within your browser on this domain:

https://localhost:44388

On the first screen of the installation wizard, you will be prompted to create a CMS content editing admin account. Be aware that if you do not make the password strong enough, the installer will fail later on and will throw an unhelpful unknown error. So my tip is that if you have problems with the installer, come back here and make the password more secure!

'## Should I Upgrade My Existing Website To Use Umbraco 14?

Installing a vanilla blank website should be your go to option for all new Umbraco sites, however, if you already have an existing site should you upgrade? Granted some versions of Umbraco are easier to upgrade, while others are more complex and Umbraco 14 could fall into the harder upgrade paths depending on your site.

in terms of upgrades there are two important things to be aware of. The easy to understand one is your feeling around support and effort. In case you didn't know, the Umbraco release schedule mirrors that of the .NET framework, meaning we have long-term supported versions (LTS), and short-term supported versions (STS).

Umbraco 14 is built on .NET 8. It is a STS version. The next release of Umbraco will be around Christmas time. Version 15 will run on .NET 9. .NET 9 is a standard-support version of .NET and Umbraco. If you only want to upgrade to long-term supported versions, then you will need to wait until November 2025 for Umbraco 17 as that's the next planned LTS release. More information can be found here:

  • .NET and .NET Core Support Policy
  • [Umbraco Long-term Support (LTS) and End-of-Life (EOL)](Long-term Support (LTS) and End-of-Life (https://umbraco.com/products/knowledge-center/long-term-support-and-end-of-life/)

If you are building a brand new Umbraco site, you should use v14, however, if you already have an existing site then you might not necessarily want to upgrade. Obviously, only you can judge the time/effort benefit of upgrading within your team, however, to make that decision there are three main considerations you need to be aware of. In this section, I will share some tips to help you decide if upgrading makes sense for you.

Whenever you are considering an Umbraco upgrade, the first bit of information that you need to understand in order to make an informed upgrade decision is the support timeline for that version.

When Microsoft releases a new version of .NET, they release a version as either long-term supported releases, or, short-term. If you want to minimise upgrade effort, the advice is to only upgrade when Long-term supported versions are released.

Umbraco 14 is built on .NET 8 and Microsoft released .NET 8 as a STS version. This means Umbraco also has to classify Umbraco v14 as a STS version. If you follow a STS release cycle you will need to upgrade your site twice a year, compared to following a LTS cycle of upgrading roughly once every two years!

The next release of Umbraco (v15) will be around Christmas time 2024. This version will run on .NET 9. and .NET 9 will also be shipped by Microsoft as a standard-support version of .NET.

If you only want to upgrade to long-term supported versions of Umbraco, then you can hold off upgrading until November 2025 for Umbraco 17! More information can be found here:

  • .NET and .NET Core Support Policy

  • [Umbraco Long-term Support (LTS) and End-of-Life (EOL)](Long-term Support (LTS) and End-of-Life (https://umbraco.com/products/knowledge-center/long-term-support-and-end-of-life/)

LTS and STS aside, the next upgrade consideration is your risk tolerance. v14 contains big/major breaking changes. If you have code that relies on a deprecated feature, you will need to rewrite/refactor a lot of your codebase to make things work again.

From my experience, big CMS changes are great but typically they make upgrading custom code harder as more things break. Also, its not only your custom code that you need to worry about. If your site uses a third-party package, that package may also break when upgrading. When this happens, you can be left with no alternatives.

The main risk here is the first-person in the que problem. Lets say you bump into an issue when you are upgrading, it is likely that you will be the first person to encounter this issue.

When this happens, finding information on how to fix the issue may be non-existent. When you get stuck like this, you will then need to waste a bunch of time trying to solve the challenge yourself.

In worst-case scenarios, you might even be forced to ditch the upgrade until the next CMS release as waiting for third-party package vendors is too time intensive! If the issue is with the core CMS, you may need to raise a support ticket and wait for the CMS to be patched.

Trust me on this, being the first to hit an upgrade error can waste a lot of time and by waiting you can let someone else do the hard work for you.

As we will talk about in the next section, the big changes in v14 occur in the backend. A big factor on how easy it is to upgrade your site will centre around how much you have customised your Umbraco backend.

In terms of breaking changes, macros, the old media picker, the grid layout property, and the nested content property have all been deprecated. If your site uses any of these, you will need to scheduled time to fix each one, as well as do some content migration and some testing. If you have written a bunch of custom backend components, these will likely need to be recreated.

Umbraco 14 Feature Tour

We have finally got to the fun bit... what new features do you get with v14?

Within Umbraco 14 the main scope of change is around the backend. however, on first glance the level of change is not obvious. After you log-into the backend, you wont see a bunch of new features, there are no new sections, data-types, views, or anything else. In fact, you will probably think things look very similar to v13.

Do not be fooled by the subtle, the big change is that the whole backend UI has been rewritten!!! This is why this release is deceiving. v14 won't give you any new ground-breaking features, however, how you build backend extensions is now completely different and this will have a big impact in the future!

As part of the new UI, as a developer there are three things you need to be aware of:

  • New Umbraco UI library
  • New Headless Management API
  • New Frontend SDKS to help you create custom backend extensions

This new backend, code-name Bellissima, is a move away from Angular and a move towards a standardized Umbraco UI library that is powered with Web Components and APIs. The UI library is open-source and huge. It contains over 100 components and you can play with all of them from the official UI library website here:

Within this library you will find components to render action bars, buttons, cards, menu items, pagination, tabs, and more...

In previous versions of the CMS, it was left to a developer to make their custom backend stuff look like it belonged within Umbraco. To build backend stuff you either needed to know Angular, or .NET and it was left up to the developer to make their custom views look like an Umbraco component. If you used .NET, you could hack the CSS to make life easier, however, it was a pain. This lack of standardisation meant that the custom stuff, looked very different from the Core stuff.

So the first big change is that the backend has been rewritten to use these components. These changes are not just CSS tweaks, but a completely new architecture.

With that insight covered, the next thing to consider is how will Umbraco get the data from the database and pass it into those components?

Management API: In the past few versions of Umbraco, its headless API support has grown and v14 is no different. In v14, you get a Management API. This API will allow developers to do CMS related tasks over REST API. These tasks include, creating document-types, reading web hooks, creating a data-type, viewing audit-logs etc...

In essence, the tasks that you might want to trigger in order to power the data within the new UI components have now been exposed via REST API!

In v14, you get about 100+ new end-points within the Management API. Pretty much anything you can do as a editor within the CMS, is now exposed via an end-point within the Management API. This move is definitely handy for headless website developers as it means you can do a bunch of CMS operations within your headless app now!

The best way to look at the what the management API offers is via Swagger locally. See the related video to learn how to launch swagger locally and access the management API

Extension and Context SDK: The final big change that you need to understand is around extensions and third-party component. With v14, the way you create extensions has changed. Extension developers now need to be build extensions via a new API/SDK layer. There is a good diagram on this page to show you the architecture (see here), however, in essence you have an Extensions API and a Context API. One thing not to get confused here is that these are not REST APIs like the management API. These are APIs you can use within a a JavaScript powered project to render stuff within the CMS. You can learn more about these APIs/SDKs from : - @umbraco-cms/backoffice - GitHub

So as you can now hopefully appreciate, this release is monumentally big, however, in terms of new stuff content editors can use pretty small. As the entire focus of v14 is backend change, there is nothing else to cover here. There are v14 updates to Workflow, Deploy, Commerce and Forms but for time, etc... I won't anything here.

I will cove my thoughts on this new backend as well upgrade guides and extension guides in separated blogs/videos. If anyone would like a deep-dive video on any of these topics let me know. Happy Coding 🤘