Umbraco Extension Template May Lead To Conflicts In Packages

Mar 9, 2025 by ADMIN 61 views

Introduction

Umbraco is a popular open-source content management system (CMS) that allows developers to create custom extensions and packages to enhance its functionality. The Umbraco Extension template is a starting point for creating new packages, but it may lead to conflicts in packages if not used properly. In this article, we will discuss the issue and propose a solution.

Umbraco Version

We are using Umbraco version 15.2.3 in this example.

Bug Summary

Assume two developers start their package with the Umbraco Extension template and let some of the configuration unchanged. Then these packages may cause conflicts and override their methods, etc.

Specifics

Issue Details

There are some places where the examples need to be changed. And I think these are not obvious to beginners.

Client Folder: The Client folder is not changed to something unique like the package name.
Custom Element Name: The customElement name and maybe the related class name in dashboards.element.ts are not changed.
Meta Pathname and Label: The meta:pathname and meta:label in dashboards/manifest.ts are not changed.
API Services: Even more tricky might be export const client = createClient(createConfig()); in api/services.gen.ts. I am not sure if this is an issue. It seems to work and did not see errors in Dev Tools.

My Proposal for a Solution

I have manually changed the above-mentioned names, and here are some screenshots of how the Dev Tools should look like:

Steps to Reproduce

Create two packages with the Umbraco Extension template.
Change some text in the render() method in one of the example dashboard.element.ts.
Create the packages for your local NuGet source.
Install both packages into a new Umbraco WebSite project.
Run and see that you don't two different dashboards. In Dev Tools: Sources tab, you'll see just one Client folder, etc.

Expected Result / Actual Result

I would expect from such a template that it does all necessary changes to produce a unique starting point for a new package. At least there should be a detailed checklist for what needs to be changed. But we all know that such lists tend to be overlooked or ignored.

Conclusion

The Umbraco Extension template may lead to conflicts in packages if not used properly. To avoid this issue, it is essential to change the Client folder, custom element name, meta pathname and label, and API services as mentioned above. I propose a solution to manually change these names and provide a detailed checklist for what needs to be changed. By following these steps, developers can create unique starting points for their new packages and avoid conflicts.

Recommendations

Change Client Folder: Change the Client folder to something unique like the package name.
Change Custom Element Name: Change the customElement name and maybe the related class name in dashboards.element.ts.
Change Meta Pathname and Label: Change the meta:pathname and meta:label in dashboards/manifest.ts.
Change API Services: Change export const client = createClient(createConfig()); in api/services.gen.ts if necessary.

Introduction

In our previous article, we discussed the issue of the Umbraco Extension template leading to conflicts in packages. We proposed a solution to manually change the Client folder, custom element name, meta pathname and label, and API services. In this article, we will answer some frequently asked questions (FAQs) related to this issue.

Q: What is the Umbraco Extension template?

A: The Umbraco Extension template is a starting point for creating new packages in Umbraco. It provides a basic structure for developers to build their custom extensions.

Q: Why does the Umbraco Extension template lead to conflicts in packages?

A: The Umbraco Extension template does not change the Client folder, custom element name, meta pathname and label, and API services to unique values. This can lead to conflicts when two or more packages are installed in the same Umbraco project.

Q: What are the consequences of using the Umbraco Extension template without changing the necessary values?

A: The consequences of using the Umbraco Extension template without changing the necessary values can be:

Conflicts between packages
Overriding of methods and properties
Inconsistent behavior of the package

Q: How can I change the necessary values in the Umbraco Extension template?

A: To change the necessary values in the Umbraco Extension template, you need to:

Change the Client folder to something unique like the package name
Change the customElement name and maybe the related class name in dashboards.element.ts
Change the meta:pathname and meta:label in dashboards/manifest.ts
Change export const client = createClient(createConfig()); in api/services.gen.ts if necessary

Q: What is the best practice for creating a new package in Umbraco?

A: The best practice for creating a new package in Umbraco is to:

Use the Umbraco Extension template as a starting point
Change the necessary values to unique values
Test the package thoroughly before releasing it

Q: Can I use the Umbraco Extension template without changing the necessary values?

A: While it is technically possible to use the Umbraco Extension template without changing the necessary values, it is not recommended. This can lead to conflicts and inconsistent behavior of the package.

Q: How can I avoid conflicts between packages in Umbraco?

A: To avoid conflicts between packages in Umbraco, you can:

Use unique values for the Client folder, custom element name, meta pathname and label, and API services
Test the package thoroughly before releasing it
Use a version control system to track changes to the package

Conclusion

The Umbraco Extension template may lead to conflicts in packages if not used properly. By changing the necessary values and following best practices, developers can create unique starting points for their new packages and avoid conflicts. We hope this Q&A article has provided valuable information to help developers avoid conflicts between packages in Umbraco.