I am thrilled to announce that Clean Starter Kit v7 was released on Thursday 27th November, on the same day that Umbraco 17 was launched.
Umbraco 17 is a Long Term support release (LTS), meaning it will be supported for the next three years. Meanwhile the previous LTS Umbraco 13, has now entered the security phase and will no longer receive new features.
I have decided to target the Clean Starter Kit’s source code to Umbraco 17, allowing us to benefit from the new Umbraco back office, the management API, and more. We’re essentially drawing a line in the sand and moving forward with Clean Starter Kit on this modern foundation.
What is Clean Starter Kit?
For those who haven’t come across Clean Starter Kit before, it’s essentially a set of NuGet packages. The main package, called Clean, is installed into your empty Umbraco website, and it sets you up with document types, content, templates, and more, giving you a simple, demo-ready blog website. This makes it easy to test out Umbraco versions, demo Umbraco to colleagues or clients, and test other packages in a ready-made environment. It’s perfect for conference talks and quick demos.
Initially, it’s just a straightforward demo website, but it can also serve as a foundation for your own project if you want to expand on it.
For example, the CodeShare website (codeshare.co.uk) uses v4 of Clean Starter Kit, and then it was customised further. That’s the beauty of it: if you just need a quick demo, the Clean NuGet package is perfect. If you want to build on the code and customise it, then the dotnet template version is the way to go.
Installation Instructions
Nuget Package
# Ensure we have the version specific Umbraco templates
dotnet new install Umbraco.Templates::17.0.0 --force
# Create solution/project
dotnet new sln --name "MySolution"
dotnet new umbraco --force -n "MyProject" --friendly-name "Administrator" --email "admin@example.com" --password "1234567890" --development-database-type SQLite
dotnet sln add "MyProject"
# Add Clean package
dotnet add "MyProject" package Clean --version 7.0.1
# Run the project
dotnet run --project "MyProject"
# Login with admin@example.com and 1234567890
# Save and publish the home page and save one of the dictionary items in the translation section
# The site should now be running and visible on the front endPowershell script to install Clean v7 in as a NuGet package in a new Umbraco 17 website
⚠️ Important: After your site is set up and running, switch from the Clean package to Clean.Core to prevent views and assets from being overridden:
dotnet remove "MyProject" package Clean
dotnet add "MyProject" package Clean.Core --version 7.0.1Switch to the Clean.Core package after installation
dotnet template method
# Install the Clean Starter Kit template
dotnet new install Umbraco.Community.Templates.Clean::7.0.1 --force
# Create a new project using the template
dotnet new umbraco-starter-clean -n MyProject
# Navigate to the project folder
cd MyProject
# Run the new website
dotnet run --project "MyProject.Blog"
# Login with admin@example.com and 1234567890
# Save and publish the home page and save one of the dictionary items in the translation section
# The site should now be running and visible on the front Dotnet template installation instructions
✨ Note: As of version 7.0.0, the template now supports periods in project names (e.g., Company.Website). Previous versions had a limitation that prevented using periods due to internal class naming conflicts, which has been resolved.
The Motivation Behind the Update
About a month ago, Andy Butland, the Head of the CMS at Umbraco HQ, made a pull request for Clean Starter Kit to target .NET 10 and Umbraco 17. This revelation showed me that Umbraco HQ themselves rely on Clean Starter Kit in their automation tests. That was a huge compliment and really motivated me to get the starter kit up to date.
After attending the Umbraco Manchester meetup, I realized that more developers were relying on Clean Starter Kit, and it was time to modernise it and introduce new features.
In this new v7 release, I worked with Joe Glombek to improve the block list label values using the new Umbraco 17 UFM (Umbraco-flavored Markdown) and the updated label properties. Joe also enhanced property descriptions and document type descriptions, ensuring that the kit remains user-friendly and robust as more people adopt it.
These improvements are the main highlights of the v7 update, making the Clean Starter Kit more powerful and user-friendly than ever before.
Embracing Automation for Faster Updates
Previously, the packaging and deployment processes were slow and manual, which took up too much time for me to release updates and also allowed for human errors to happen.
I realised that to move quickly with updates and encourage contributions from others, I needed to replace the manual processes with automation. Since the repository is hosted on GitHub, and GitHub Actions are available for free on public repos, I dedicated the last few weeks of evenings to restructure the repository and create a suite of automated workflows. So as of now there are 5 key GitHub Actions that support the Clean Starter Kit.
Pull Requests
The first GitHub Action triggers whenever a pull request is submitted. The action pulls down the code from that branch associated with the pull request, attempts to build it, runs the site, and even takes screenshots of both the front-end pages and the content pages within the Umbraco back office. This ensures that I can easily spot any issues or breakages right away, making the whole process far more efficient and reliable. It does this for the nuget package version and the dotnet template version.
Scheduled Dependency Updates
In addition to the pull request workflow, there’s another GitHub Action that runs on a schedule. Every morning this workflow scans through all the projects within the repository and checks in NuGet for newer package versions, and if any are found, it updates the project files accordingly and runs a build to ensure everything is stable. If the build succeeds without errors, it then creates a pull request with these changes that includes a message with details about which packages and projects were updated. This pull request then triggers the pull request workflow, which I mentioned earlier, that runs all the tests and checks, including the screenshots of the front-end and back-office pages. This creates a seamless, automated feedback loop, ensuring that the Clean Starter Kit remains up-to-date and robust.
Streamlined Release Workflow
Another powerful GitHub Action I’ve implemented is the release workflow. Now, I can handle releases right from my mobile phone if I want to, whereas before, I had to rely on my laptop and perform a series of manual steps.
With the new workflow, I simply create a new tag and draft a release on GitHub. Once I save the release, the workflow takes over and automates everything that used to be manual. It builds and packages the NuGet packages in the correct order, then deploys them to NuGet, saving me the hassle of manual uploads.
Additionally, it creates a pull request which updates the documentation automatically, ensuring that the readme files and the Umbraco marketplace samples always reflect the latest version of Clean Starter Kit. This means that the entire release process is now seamless and efficient, and I can manage it from anywhere.
Additional Testing on Released Package Versions
I soon realised that while the new automation made releases much more convenient, it was crucial to ensure that every package was thoroughly tested before it reached the public. Even with automated checks, there’s always a possibility that something could slip through. To address this, I introduced another GitHub Action specifically designed to test the latest version of Clean Starter Kit that is in NuGet with the latest version of Umbraco in NuGet too.
This workflow installs the latest packages, runs builds, and performs the same comprehensive testing, including taking screenshots of both the front-end and the Umbraco back office. As a result, I get reassurance that the released package is stable and functioning perfectly, giving me confidence that everything is in order before it reaches the public.
Managing GitHub Package Versions
As part of my automation, I publish the built packages to a GitHub package feed. This allows me to test the new versions thoroughly before doing the full public release. Every time the PR workflow runs, it uploads CI build versions of these GitHub packages, and over time, older versions can accumulate and clutter the feed. To keep things tidy and manageable, I created another workflow that automatically cleans up these old package versions. This ensures that the package feed remains clean and that we don’t accumulate unnecessary clutter, making it easier to manage and navigate future releases.
Contributing to Clean Starter Kit
If you have ideas for improving Clean Starter Kit and want to get involved, here are the steps to get started.
First, fork the Clean Starter Kit repository on GitHub and clone your fork to your local machine. Make sure you have .NET 10 installed and the you can build and run the Clean.Blog project. When you do this, uSync will automatically add all of the document types, settings and content in a SQLite database, so you won’t need to worry about database setup or content creation. This is thanks to Kevin Jump’s uSync package and the first boot feature, making it easy to have a consistent environment.
Once everything is set up, you can make your changes on a new branch in your fork. When you’re ready, submit a pull request to the main repository. The GitHub Actions will automatically kick in, running all the tests and checks, including the screenshots of the front-end and back-office, so you can be confident that your contributions are thoroughly validated.
This process ensures that contributing is straightforward and that every pull request is tested and validated, making it easy and reliable to contribute to Clean Starter Kit.
I hope you’ve enjoyed hearing about the new era of Clean Starter Kit and I can’t wait to collaborate with you to make it even better and more useful in the future.