Umbraco 14 Release Candidate

Overview:

• New Client-side Architecture
  • Built with TypeScript
  • LIT, Web Components, and UUI
• Consolidated Service Architecture
• Breaking Changes and Deprecations in Umbraco 14
  • Bye Json; Hi Json
  • Cleaning up legacy editors and functionality
  • Xpath is in the past
• Known issues
• What about Forms, Deploy, Commerce, and Workflow?
• Getting started with Umbraco 14 RC
• What’s next?

2024-05-29: Umbraco 14 RC5 is released see release notes for details on changes.

New Client-side Architecture

We might as well get it out of the way from the get-go: In Umbraco 14 there is no AngularJS. It’s gone. 

Instead, you’ll find a new implementation of the Backoffice using TypeScript, Web Components, LIT, and the Umbraco UI Library. We want to be as technology agnostic as possible and at the same time give developers, agencies, and end-clients all the tools they need to succeed. 

Hand in hand with the new technology, we’ve also set a new standard for, where and how much you can extend the Backoffice. Internally, we’ve used the term “Extension First Strategy”, meaning, that wherever possible, we’ve implemented the Backoffice in a way, so that your extensions can be implemented the same way. From Login, over Sections, to Trees and Buttons, no special advantages have been afforded to the Backoffice default features. It’s all built with tools that are available to you too! 

This leads to a bunch of new opportunities for package developers, and way more extension points, and we can’t wait to see what creative solutions that will lead to.

Built with TypeScript

We use TypeScript so that we can produce Javascript more safely with better integration to our IDEs. We also deliver definition files so that you can use IntelliSense for our APIs within your IDE. That means support for strong typing and a less error-prone developer experience. Our examples on our docs platform will use TypeScript too.

So if you are going to follow our code examples or maybe contribute to the source code, please start adopting TypeScript, as that’s a basic fundament for our Backoffice in Umbraco 14 and beyond. 

However, if you are already an expert in a specific frontend framework, that can be used for your packages too.

LIT, Web Components, and UUI

While we, together with TypeScript, use Lit and our Open Source Umbraco UI Library for implementing the user interface for the Backoffice, you, as a package developer, can choose whatever framework you want, - as long as you can build Web Components with that framework. That’s friendly, isn’t it?

If you are an existing package developer, and maybe even learned AngularJS to be able to implement packages for Umbraco - it might feel a bit annoying to now learn something new. Luckily, you are not alone in learning that “something new”. We’ve docs that describe the basic setup and installation, tutorials and docs that help you get started with extensions, and much more. Also, both Nathan Woulfe, Matt Brailsford and Andy Butland from our DXP team have shared some of their experiences working with Bellisima. Watch this video “Practical Adventures with Bellissima” by Nathan, or read the articles “Creating your own UI extension points” (Matt), “Back to the Front-end” (Matt), and “First Steps with Umbraco 14” (Andy). Those, and a bunch of other good resources from Kevin Jump, Lee Kelleher, and other good people can be found in our Umbraco v14 Bellissima Resources list. That also includes our newly open-sourced client code for Umbraco Workflow, which could maybe serve as inspiration for your projects. 

With the introduction of the Umbraco UI Library, we’ve ensured consistency in the UI across the Backoffice. It’s now easier for you, whether you’re developing a package or extending functionality, to align and implement the same friendly user experience as we strive for in the Backoffice. It's pre-set with the same nice styles that you know from previous Umbraco versions, it takes care of some of your accessibility concerns, and it’s available to be experimented with through the integration to Storybook. We hope it will save you some time to get started and help make it easier to maintain and evolve your UI along with the Backoffice. 

Consolidated Service Architecture

In Umbraco 14 we have moved more responsibility to the client, and we’ve re-implemented all backend endpoints to support this updated approach. 

That means, that all the endpoints used by the Backoffice combine to form the new Management API - an API that you can find a Swagger specification for on {yourdomain}/umbraco/swagger. In practice, these endpoints are the exposure of all our public-facing controllers. These controllers are now more lightweight than ever before, as all business logic now resides in the service layer. Simply put, just a really nice separation of concerns.

That also means, that while working with package development, all functionality can be called through services. When calling services, you should know that we’ve introduced the use of an “Attempt Pattern” (also known as the “Maybe Pattern”), to be able to have a single consistent and asynchronous way to call services while retrieving a rich status from the call. If in doubt about how to use it, then just take a look at one of the many controllers. It’s amazingly simple.

Talking about controllers and the management API, it’s now possible to programmatically control everything in Umbraco through this API. You can create Users, Members, Document types, Media, Content, and yeah - simply everything. The Backoffice is just one client - and you can (in theory) create your own Backoffice. You probably don’t want to build a client for everything, but if you have a scenario where information from one system should be transferred to Umbraco, or if you have a specific use case where an editor should be able to do something in Umbraco from within another application, that can now be done. You’ll log in the user through OpenID, and then the opportunities are up to you. Again, this opens up for creative integrations, and we’re curious about what cool usage we’ll see. 

In addition to being the most extendable version of Umbraco ever, Umbraco 14 is also the version with the most test coverage ever. We’ve added a significant amount of tests - especially integration- and acceptance tests - to increase the reliability of new contributions, whether they originate from the community or HQ. 

Breaking Changes and Deprecations in Umbraco 14

We’ve prepared for Umbraco 14 for some time and planned for the deprecation and removal of several things during the last couple of years. Umbraco 14 is not just a frontend update, it’s also a cleaned-up version for the future, where some of the not-so-maintainable implementations are removed. 

Bye Json; Hi Json

On the backend, we’ve moved away from Newtonsoft.Json and adapted the Microsoft-supported System.Text.Json. System.Text.Json is way more strict and does not aim for feature parity with Newtonsoft.Json, but you (and Umbraco) gain improved performance, security, and compliance with standards. If the stricter behavior becomes an issue for your implementation, you can still take a dependency on Netwonsoft.Json yourself, however, a safer way might be to ensure that you use a JSON format that complies with the standard, and therefore will work with System.Text.Json.

Cleaning up legacy editors and functionality

In Umbraco 14 we have also removed macros. They have caused some maintenance headaches over the years, and, as we believe we have covered all relevant use cases with alternatives like partial views and blocks in the RTE, macros are now gone. Same with the Grid Layout, Nested Content, and the Media Picker (legacy), which are all property editors that have better alternatives in the Block Grid, the Block List, and the newer Media Picker. Also, for the block-related editors, we have an RFC for Reusable Content with Global Blocks in the pipeline, which will add flexibility to the various usages of blocks. 

Xpath is in the past

Another project we have in the pipeline, or more precisely on the roadmap, is the Lazy-loaded content cache and the support for the .NET IDistributedCache interface. However, it will be impossible for us to support this new caching model, if we still need to support XPath traversing. XPath is therefore removed. As an alternative, we’ve already in Umbraco 13 introduced Dynamic Root in the Multinode Tree Picker, which offers the same level of flexibility but in a way more intuitive way - and with support for the future implementation of Lazy-loaded content.

See more in the Umbraco 14 release notes and umbraco/Announcements on GitHub.

Known issues 

The focus is on providing a good base experience of working with the new Backoffice and APIs, and that means a bit of prioritization has been needed. As such, there are a number of features that will likely not make it into the initial release of Umbraco 14. These are:

• Tours
• Help section
• Keyboard shortcuts
• Preview 

Also, in this first release candidate, you’ll not find:

• Dictionary for Backoffice translations
• Label templates
• Block live preview
• Custom icons
• Blocks Grid, Block List, and Blocks in the RTE
• TinyMce premium cloud plugins
• Various minor UI features

We will of course be (re)adding in the features as they are completed and tested. So there are a lot of back office-related things to look forward to in the upcoming versions as well.

For evaluating upgrade scenarios the Version Specific Upgrades article has a helpful list of changes that can come into consideration.   

What about Forms, Deploy, Commerce, and Workflow?

As I already mentioned we have open-sourced the client code for Workflow, - to give you some inspiration on how to implement packages in the Umbraco 14 Backoffice. Workflow is not 100% done at the time of the release candidate, but it is close. 

We are also working on migrating both Forms, Deploy, and Commerce. We expect to have RCs out of all these add-ins within the next few weeks and to have them fully available together with the final Umbraco 14 release on May 30. 

As an added benefit this means our very skilled DXP team colleagues have been working along with us during the final implementation. We continue to use their feedback to finetune the Extension API, and we’re looking forward to getting your feedback as well! Just as all the package developers out there, they too have had to get to grips with the new architecture and conventions. But they’ve learned it, shared their experiences, blogged about it, and seem to genuinely like the new opportunities they see. And the new implementations look really promising. Son’t be surprised if you happen to see even more flexible add-ons for Umbraco 14.

Getting started with Umbraco 14 RC

This RC is a great opportunity for package developers to get started. We’ll minimize breaking changes from now on, and it’s safe to get started upgrading packages. But, as mentioned, we’ve updated a lot with this release. It would be a huge help to hear from you, about how things go when upgrading your site - both small and big sites. Does it work as expected, or do you face any kind of issues? 

You can get started by following the Umbraco 14 installation guide.

Please report any issue on the Issue tracker, or comment on ideas or functionality on our GitHub discussion section.

What’s next?

This release is broadly speaking feature complete. We do expect several RCs over the coming weeks to add in the remaining functionality. As we continue to get feedback from the team updating the official add-ons and from the community testing and migrating packages, this will be incorporated in upcoming release candidates as well. 

Besides fixing potential bugs in the CMS and the HQ packages, we will also focus on making Umbraco 14 available on Umbraco Cloud and continue the efforts to document umbraco 14. 

All of this leads up to the final release of Umbraco 14, which is targeted for release on May 30, 2024.