Use this dotnet new template to get a head start on creating, releasing and maintaining packages for Umbraco 17. If you just want to extend the backoffice of your Umbraco site, you should use the umbraco-extension template directly.
I've called it an 'opinionated' package starter template because lots of decisions have been made for you. This means that all you really have to worry about is adding your package code. A lot of the other stuff involved in developing, releasing and maintaining an open source Umbraco package has been done already.
Of course none of these decisions are irreversible. Once you've used the template you can change whatever you need to. Please make sure you read this readme so you understand what choices you are starting with so that you can change them where necessary before you push to GitHub, and definitely before you publish to nuget!
Run the following command to install the template:
dotnet new install Umbraco.Community.Templates.PackageStarter
Open a command prompt in the location you want your new package repository folder to be created:
dotnet new umbracopackagestarter -n YourPackageName -an "Your Name" -gu "YourGitHubUsername" -gr "YourGitHubRepoName"
More information on the parameters to use, and what build commands to use after the template has run, can be found in the instructions.
Nothing! You can learn more about it from this section of the Umbraco 15 unboxing video or from the official documentation.
It's just that all it gives you is the actual extension project. Which is fine if you're just wanting to build custom extensions for your Umbraco instance. But if you're going to want to release this functionality as an actual package then you'll need to set up a test site, configure it for nuget, work out how you're going to release to nuget, add certain files for a well maintained repo ...
Whereas this template will create a folder with:
- A new solution (.slnx)
- A package project created using the core
umbraco-extensiontemplate - A test site referencing the package project
- A GitHub action for publishing to nuget when a tag is pushed
- A good start on:
- The readme for your GitHub repository
- The readme for your nuget package
- The
umbraco-marketplace.jsonfile which improves how your package appears on the Umbraco Marketplace
- GitHub templates to help people create good issues and feature requests
- And more!
- License: MIT
- Umbraco version: 17.0.0
- nuget package Id:
Umbraco.Community.YourPackageName(although this is configurable, see the parameters in instructions)
Because Umbraco CMS is released with an MIT license, and I've assumed you're releasing this as an open source package too.
Umbraco 17 is the current Long Term Support (LTS) release. By targeting 17.0.0, your package can be installed on any Umbraco 17 site.
If there is a need, or you want, to restrict your package to a later version of 17 then you should raise the version in Directory.Packages.props, which centrally manages package versions for both projects in your solution. Refer to issue 10 for an earlier discussion about what versions to support.
If you don't have a company or personal brand to use as a prefix, then this is a well used convention for Umbraco community projects.
If you want to create a package for an older version of Umbraco, install the appropriate version of the template. Instructions for version 13 are in the v13/dev branch.
Yes feedback, thoughts, issues, pull requests... are of course most welcome!
Please read the Contributing Guidelines.
A lot of the decisions were made whilst collaborating with Lee Kelleher (the creator of Contentment and many other Umbraco packages) whilst developing my Admin Only Property package. So big #H5YR for all your help Lee 🙏!
"out of the box" by Yoyon Pujiyono from Noun Project