Why we've embarked on this work
Packages are an incredibly important part of the Umbraco ecosystem and have been almost from the outset. They've been a way of people adding functionality to the CMS, extending it in a multitude of ways, and sharing their work for others to benefit from. Many are open-source, and some others are commercial with business being built on the back of Umbraco packages. Many features of the CMS that now come out of the box, or as an HQ offering, started life as a community package.
For finding packages, our.umbraco.com has served us well, but by now it's showing its age to an extent. We're also finding that, as Umbraco from version 9 no longer supports the installation of a package from a zip file, and requires the installation of a package from NuGet, some developers are no longer feeling the need to create a listing here.
The Umbraco backoffice also allows for the search and review of packages, via the Packages section. This uses the information from the catalog at our.umbraco.com and presents the details in a slightly different way.
And finally, we also have umbraco.com/marketplace, a searchable but separate listing of a subset of key packages, integrations, and details of our technical partners.
Our aim with this project is to replace all three of these options with a single new website, API, and data source. This will live as a standalone site at marketplace.umbraco.com and will present information on all NuGet-hosted packages for Umbraco 8+.
We will synchronize information from NuGet for all packages that opt-in to listing and provide a means for developers of packages to add additional information for display, such as screenshots, videos, and biographies.
This website will be available from the Umbraco backoffice, likely via an IFRAME.
And the umbraco.com section will be reworked to focus on presentation of technical partner profiles and content-led features around cDXP (Composable Digital Experience Platform) and related topics.
How you can get your package listed
In order to have your package listed on the new marketplace website there are two steps, one required, and one optional.
The required step is to ensure your package when published to NuGet has a tag of umbraco-marketplace.
When our scheduled synchronization process runs we search for all packages that have this tag, and import those that meet the minimum Umbraco version requirements (Umbraco 8 or above).
By doing this, your package will be listed, with the details we can obtain from NuGet. This will include the package name, icon, authors, description, readme, project URL, and other details that are part of the NuGet package specification.
Please note that you should only tag the installable component of your package that you want to be listed on the marketplace website. This will be the one that a developer would need to add to their csproj file to install it.
So for example, if you have an installable component called MyPackage, that references another package called MyPackage.Core, it's only the former that should be tagged.
Adding additional information to your package listing
For some, that may be enough, but to really show off the package's functionality, we've added a means for package owners to augment their marketplace listing.
You can do this via a file called umbraco-marketplace.json that we will look for in the root of the URL defined as the project URL in the NuGet specification.
This is listed as the "Project website" on nuget.org:
So for example, if you have a website for your project and have set the project URL to https://www.myawseomepackage.com, we will look for the file at https://www.myawseomepackage.com/umbraco-marketplace.json.
Many people will link to a GitHub repository for this project URL, and if that's the case it works in a similar way. Here we will look for the umbraco-marketplace.json file in the root of the default branch of the repository, or a deeper link if that's what you have defined.
Lastly, we want to account for people that use the same project website for multiple packages. In that case, you'll want one file for each package, and you can do that by suffixing the file name with the package ID.
So, in the example above, if the NuGet Package Id is My.Package, we'll also look for a file at https://www.myawseomepackage.com/umbraco-marketplace-my.package.json.
The contents of the file will look like the example you can find here. Please note that there could be additions and perhaps other changes between now and the launch. We'll ensure the schema is fully documented at that time.
Over and out…. for now
Hopefully, interest has been piqued and you are looking forward to seeing the new website when it is released in around a month's time. And if you are a package developer, please look to tag your packages, and look at preparing the JSON file for providing additional information. As well as ensuring your package is promoted, it helps us in having live data for testing with and ensuring we have a nicely populated catalog of packages when we launch.
The new marketplace will be available later this month, so you can see your package listing and have time to tweak the information prior to the inclusion in the backoffice. If you have any questions you can reach us at firstname.lastname@example.org.