Umbraco 13 was released on December 14, 2023. v13 is the second major Umbraco CMS version update within 2023 and like all new CMS upgrades it contains a bunch of new shiny stuff for you to know and understand.
As you are reading this article, I can only assume that you want to become a better Umbraco guru and this is where this article has you covered. Read on to learn about everything you need to know about v13, including installation, upgrades, and new capabilities. Regardless if you are creating a new greenfield build or you manage a website that uses a legacy version of Umbraco, this article will have you covered
How To Install Umbraco
The first thing to know is that Umbraco v13 makes use of .NET 8. This little fact is important because without installing .NET 8 locally first the Umbraco installer will fail.
As well as .NET 8, you also need to make sure your Visual Studio 2022 is also patched to a version that also supports .NET 8. This means upgrading VS 2022 to at least v17.8.0!
After doing that you will need to install the Umbraco v13 installation template. I find the easiest way to install these templates is via the CLI. To use the CLI run this command within a terminal:
With the v13 template installed, you can now create an Umbraco website. The first point to mention here is that the process for creating a website has been exactly the same since Umbraco 9. As long as you have the correct installation template installed locally, the website creation process is the same. To create and run a new site you can use this command:
Running this command should launch a terminal. Within the terminal output, you should be able to find the URL that you need to use in order to access your website locally. This URL is usually the first one listed within the output (depending on if you want to use HTTP/HTTPS locally).
When you find the URL, copy it within a browser to launch your site. The first thing that will launch is the Umbraco installation wizard. This wizard will install the SQL database and the admin user that you will use to access the CMs at the beginning..
From the first screen, you will need to add the details for your admin user. The email and password combo here will be the username/password combo to log into the CMS. Do not forget this otherwise when you close the debugger, you will be stuffed!
After deciding upon the admin details, you will need to decide where you want to install the Umbraco database. The default option is to use SQLLite, I do not recommend this for anything except for playing around with locally. Instead, my recommendation is to install your database into a SQL server-hosted database.
The reason why I recommend this path is because it's much easier to use a SQL Server database for production use later on. If you use SQLite you might need to re-create your database later on, however, if you are unsure about how to setup this up, I reordered a video on this topic here
Umbraco Feature Tour
With Umbraco installed, it's time to focus on the new capabilities. The first thing to mention is that the last release of Umbraco (v 12) only occurred 6 months ago (in June 2023). The next version of Umbraco is scheduled for release in 6 months' time in May 2024. This means that Umbraco can only add so many new features into any new release nowadays.
I mention this because the release schedule is so impressive and when you get two game-changing releases planned nearly back-to-back, a standard release has a lot of hype to live up to. If I'm being honest, I wasn't as excited about the new capabilities within v13 as I was for v12 or as I am for the upcoming v14.
In v12 we had a massive step forward with the release of the Content Delivery API. This was the first version of Umbraco that allowed for headless websites to be built using just the core Umbraco standalone features. This release was a massive game changer in my opinion. Read this article if you want to learn more about building headless websites with Umbraco!
On top of that, the next version of Umbraco (v14) also seems like it will be a big hitter. In v14, you can expect to see a brand-new backend that is powered by React components. This should eliminate the need to learn Angular 1 and should make it much easier to build admin components. Personally, I think that one of the main reasons to pick a traditional CMS nowadays over a SASS equivalent is the ability to create and customize the backend, so I am very much excited about v14...
So with v12 and v14 containing two game-changing features, the question remains... why v13? Well, one big factor for people who already own an Umbraco website is that v13 is an LTS (long-term support) release.
I bang on about LTS and STS every single time I write about a new Umbraco release because it's an important consideration. In case you weren't aware, Microsoft has two support models when they release a new version of .NET. Long-term support versions will be around for 3 years, STS versions will be supported for 18 months.
The reason for providing two different support periods is simple. As a content creator, it's great .NET is constantly releasing things as it gives me a lot to write about, however, for someone who needs to maintain a bunch of Umbraco websites having to upgrade a bunch of sites every 6 months is not realistic.
I do not want to spend all my life simply keeping all the sites I manage up-to-date. This is why the LTS releases give you an indication of when you should upgrade. If you only upgrade to LTS, this means you only need to upgrade your site every 3 years! As v13 is an LTS release, this means if you are running a site that uses Umbraco 9 to 12, you should update to this version!
Aside from support, you get a few new features:
- Minimal hosting is supported out of the box, without hacks now
- Content Delivery and Media Library API v2
- Blocks in the Rich Text Editor
- Allow Concurrent Logins
There are also some UI updates like a new login screen as well as the usual package updates and a bunch of breaking changes. As always if you want to learn more about some of the breaking changes that could cause your upgrade to fail, I recommend having a look at this article.
Minimal Hosting: Minimal hosting was a development simplification that was released within .NET 6. In .NET 5, in order to configure how your application booted up you had to make use of two files,
program.cs. Microsoft thought that having two files to do the same thing was a bit pointless, so minimal hosting was released to combine both of these files into a single entity,
program.cs. Even though minimal hosting has been around for a while, Umbraco has never fully supported it until now.
Within v13, you can now create a project with
program.cs out-of-the-box with no hacks. This also extends to the default Umbraco template, so when you create a new application it will also only use
program.cs. Previously, to get minimal hosting to work in v12 you had to use some hacky code that looked like this:
Now I am not taking credit for figuring out this hack. I admit I copied it online when I upgraded my website to v12 (and can not remember where I got it) but this is no longer needed. On top of this, Umbraco has also updated the exception messages thrown within
program.cs to make it more obvious if you are not doing something correctly.
Web Hooks: This is the big new feature within v13 in my opinion. From v13, when you log into the backend and go to
Settings, you will see a new entry in the main left-hand menu called
Webhooks are useful as they will allow you to configure Umbraco to ping a URL when certain CMS activities are made. This is useful if your CMS is attached to a headless website and you need to regenerate your static files when a new page is created or deleted. This is also really handy if you have a more complex caching strategy and you simply want to clear your cache when content is changed within the CMS.
In my opinion, this definitely was a missing feature for building headless with Umbraco so it's great it's now within the core product. In my Umbraco headless wishlist, if we could get a frontend NPM pacakge that wrapped the API, we'd have the trifecta of headless essentials within our toolkits. As I said in my v12, the rapid pace at which Umbraco is releasing new capabilities at the moment is so impressive that I'm sure this will come at some point!
New Content Delivery End-Point and Media Library API: Within the Content Delivery API, you can now add nested field limiting and nested field expansion. From the Umbraco documentation, the motivation to create this feature was to aid sites that use Umrbaco Commerce. Being able to generate a PLP page and get all the related information about all of the related products in one hit is an e-commerce 101 staple. By allowing more flexibility on what data is returned from nested content within the content delivery APIA will make things that much easier when rendering your pages.
Another way of solving this issue would be to make use of GraphQL, however, out of the box, Umbraco does not have GraphQL. Instead, you would need to build something yourself or use HeartCore that provides Heartcore (the SASS version of Umbraco). Another tweak is within the Media Library API. The Media Library API failed to get released within 17.0 and was only released in 17.2. This Media Library API isn't really adding new features, however, it did have some breaking changes that are worth mentioning.
Blocks Within The RichText Property: This new capability is a content modeling improvement. From v13, it is now possible to allow editors to pick from blocks within the rich text editor to add to a page. Personally, I prefer to use the block-list editor and create a rich-text block to provide this type of feature to a content editor, however, for those of you who want to allow the editor to do everything within a single rich text field, you now have the ability!
Umbraco Dynamic Tree Picker Property Dynamic Root Feature: This is a bit of a minor improvement around the multi-node tree picker. Previously, you could only define the logic of how to pick the starting node of the property using XPath. Now, you have a bunch of options, including XPath, I think this will likely be useful for headless websites, that need to render say listing pages.
Login UI Update & Allow Concurrent Logins: The final two features are login-related. The first thing that you will notice is that the login screen has been updated.
The second thing to note is there is now some validation around concurrent logins. by default, concurrent logins will not be allowed. From my testing locally, I was able to sign in and make updates within two different browsers on
localhost, however, this feature is definitely not aimed at localhost. In case you are interested you can configure this feature within
app.settings. like this:
In summary, if you want to upgrade an existing site this is the version you should upgrade to. If you are planning a new Greenfield project, I always use the latest version which means v13 is the version you want to use here as well.
Happy Coding 🤘