Clean 19.0.0-rc02

Clean Starter Kit for Umbraco

A modern, clean, and fully-featured starter kit for Umbraco CMS that provides a ready-to-use blog theme with headless/API capabilities. Built with Bootstrap and designed to get you up and running quickly with Umbraco 19.

Clean targets Umbraco 19 (STS), currently a release candidate. From version 19, the Clean major version matches the Umbraco major version. For complete version mapping for previous versions, see the Versioning and Releases documentation.

For detailed information about the package architecture and the different NuGet packages, see the Package Architecture documentation.

Documentation

To see what the starter kit does, with screenshots of the website and the backoffice, read the Feature Guide. It covers:

• Pages: every page type, on the website and in the backoffice
• Content blocks: the rows editors build pages from, and their spacing and hide settings
• SEO, navigation and site settings: meta tags, visibility, the menu, the XML sitemap, the footer, dictionary items and security headers
• Backoffice structure: document types, compositions, Library categories and Data Types

For detailed documentation about this package and the repository, please see the docs.

GitHub Workflows and Automation

The project uses automated workflows for continuous integration and deployment. Please see the workflow docs.

Installation

Prerequisites

Download and install the latest .NET 11 SDK or higher for your operating system (Windows, Mac, or Linux).

Umbraco 19 (STS)

🧪 Pre-release: Clean 19 is a release candidate and runs on Umbraco 19.0.0-rc1. Use it to try out Umbraco 19, not for production sites. Clean for Umbraco 19 needs the .NET 11 SDK.

NuGet Package Method

# Ensure we have the version specific Umbraco templates
dotnet new install Umbraco.Templates::19.0.0-rc1 --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 19.0.0-rc02

# 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 end

ℹ️ Data Types: Installing the Clean package arranges the Data Types tree into two folders. Clean holds the starter kit's own Data Types, and Umbraco Defaults holds Umbraco's built-in ones, which keep their names, keys and settings.

ℹ️ Models Builder: Clean's views use the models that Models Builder generates for your site, so the site needs a models mode that generates them. Create the project with the default development mode, as above: dotnet new umbraco then references Umbraco.Cms.DevelopmentMode.Backoffice, which generates the models in memory. In Umbraco 19, ModelsMode defaults to Nothing without that package, and Clean's views will not compile. If you want models as source code instead, change Umbraco:CMS:ModelsBuilder:ModelsMode after Clean is installed and running.

⚠️ 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 19.0.0-rc02

dotnet Template Method

# Install the Clean Starter Kit template
dotnet new install Umbraco.Community.Templates.Clean::19.0.0-rc02 --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 end

✨ Note: As of version 8.0.0, the template now supports periods in project names (e.g., Company.Website).

Upgrading from Clean 8.x

Read Umbraco's Umbraco 19 upgrade notes first. These points affect Clean sites in particular:

• Image URL key: on .NET 11, a site whose Umbraco:CMS:Imaging:HMACSecretKey is not canonical Base64 does not start. A key is canonical when decoding it and encoding it again returns the same string. Keys that Umbraco generates are canonical, so check any key that was set by hand. Correct the key rather than generating a new one, so image URLs already signed with it stay valid: only the final character changes, for example zx== becomes zw==. In Windows PowerShell, [Convert]::ToBase64String([Convert]::FromBase64String('<your key>')) returns the corrected key.
• Models Builder: ModelsMode now defaults to Nothing unless the site references Umbraco.Cms.DevelopmentMode.Backoffice, and setting InMemoryAuto without that package stops the site at startup. Keep the package, or move to a source code models mode, before you upgrade.
• Changed defaults: Umbraco:CMS:Imaging:Memory:Enabled and Umbraco:CMS:ScheduledPublishing:AlignToClock now default to true. Set them to false to keep the Umbraco 18 behaviour. Connect Timeout in the connection string no longer sets the database command timeout, which drops to the provider default of 30 seconds. Set Command Timeout in the connection string, or Umbraco:CMS:Global:DatabaseCommandTimeout, if the site relied on it.
• Data Types: upgrading the Clean package does not rename or refile the Data Types on a site that already has Clean. The new names and folders only apply to new installs.

Umbraco 18 (STS)

If you need to use Clean with Umbraco 18 (STS), use the latest 8.x release. The dev/v8 branch on GitHub is where ongoing Umbraco 18 development takes place.

• NuGet: dotnet add package Clean --version 8.0.2
• Branch: dev/v8

Umbraco 17 (LTS)

If you need to use Clean with Umbraco 17 (LTS), use the latest 7.x release. The dev/v7 branch on GitHub is where ongoing Umbraco 17 development takes place.

• NuGet: dotnet add package Clean --version 7.0.8
• Branch: dev/v7

Umbraco 13 (LTS)

NuGet Package Method

# Ensure we have the version specific Umbraco templates
dotnet new install Umbraco.Templates::13.14.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 4.2.2

# 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 end

ℹ️ Data Types: Installing the Clean package arranges the Data Types tree into two folders. Clean holds the starter kit's own Data Types, and Umbraco Defaults holds Umbraco's built-in ones, which keep their names, keys and settings.

⚠️ 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 4.2.2

dotnet Template Method

# Install the Clean Starter Kit template
dotnet new install Umbraco.Community.Templates.Clean::4.2.2 --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 end

Getting Started

After installation, you'll need to:

1. Login to Umbraco: Navigate to /umbraco and login with the credentials you specified (default: admin@example.com / 1234567890)
2. Publish the Home Page: Go to the Content section and publish the home page
3. Save Dictionary Items: Navigate to the Translation section and save at least one dictionary item to initialize translations
4. View Your Site: The frontend should now be accessible at the root URL

Support and Resources

• GitHub Repository: https://github.com/prjseal/Clean
• Issues and Bug Reports: GitHub Issues
• NuGet Package: https://www.nuget.org/packages/Clean
• License: MIT

Authors

• Paul Seal - Main Package
• Phil Whittaker - Headless Extensions

Legacy Versions

Looking for Clean for Umbraco V9-12? Visit the Clean Starter Kit for Umbraco v9 repository.