Where to start for first Umbraco 17 package?

Questions
,
1

I am about to embrak on writting my first package for Umbraco and am going to target v17. I am looking for advice for someone who has never written a package or done any extending of Umbraco. I know I am going to have to learn TypeScript (I think that is what it is called) for the backoffice and I think I once saw someone had like a starter template that might help a good place to start?

Any advice would be apreceated. The package will need it’s own tab in the backoffice and will also allow new properties to be added to document types.

Thanks

2

hey matthew :waving_hand:

Great :raising_hands: welcome to the fun side of Umbraco :grinning_face_with_smiling_eyes: :umbraco-heart:

I’d suggest starting small:

  • Create a basic custom section (just render something simple).

  • Then explore adding a property editor.

  • Use existing packages like Kevin Jump’s examples as reference they’re super helpful for structure.

don’t try to build everything at once. Get one small piece working, then expand from there.

u can follow these examples structural inspiration Edit: (Note These examples are not specifically for v17):

and hey if u can set this up : GitHub - umbraco/Umbraco-CMS-Backoffice-Skills this will really help u if ur working with ai tools like claude , cursor. and we’re always here on the forum to help

goodluck

3

I am going to be contrarian and say please do not start there, they are very outdated and you’ll get frustrated.

Up to date docs are here:

Use the Umbraco Extension template which will give you a few working examples too:

And as noted, AI Skills are in beta and they can greatly accelerate what you’re trying to do:

The skills are initially designed to work with Claude but I understand other LLMs can use them as well.

4

oopsee🫣

I mainly mentioned those as structural inspiration as myself started from those, but you’re absolutely right for v17 it’s much better to start from the latest docs and current extension patterns

5

And if you want to get a leg up/quick start to see how things are working rather than spending loads of time setting up your development environment for the package then…

LottePitcher/opinionated-package-starter: Get a head start when creating Umbraco Packages

(mentioned in the docs too Umbraco Extension Template | CMS | Umbraco Documentation )

the docs tend to be super simple set up one dashboard, one property editor when you very quickly expand out and the opinionated-package-starter has the infrastructure there for multiple components in your package… as well as a test site, and the release cycle too!

2 Likes
7

Thanks this is what I was trying to remember for a template. I will start with getting that setup. Good to know that it has a test site to, I had forgoten to ask about that part.

8

Thanks for the links to the docs. I will defeinatly be going thought them. I don’t want to use AI in my projects but thanks for linking that resource.

9

This might also help a little (code samples are up to date for v17 latest), it is not 100% complete as the article is still a work in progress but may be of use (give me a shout if you have questions)

Building a Custom Polls Feature in Umbraco 17 Backoffice

10

I just got the optional package installed and working, and looked at the tutorial on the Umbraco docs page and the building a custom polls feature you linked, but I don’t understand where to start. The opinioned package does not seem to have the same structure as talked about in either source so I am lost at where to start.

Does anyone know a good tutorial for creating a package using the opioniated package?

11

Maybe start with something simple like a custom dashboard

Creating a Custom Dashboard | CMS | Umbraco Documentation

12

The problem is that the umdocs and that pill tutorial have diffent folder structures vs the opinionated package. I am just trying to figure out where all the files are supposed to go inside the package. Take the dashboard example you linked for umbraco. It says to create in the appsettings folder but the opionated package does not use that folder. I cant find anything telling me how the folder structure works and that is all i need to know so i can start messing with code and figuring the rest out.

13

After re-reading my last post I think I need to open a new thread. Thanks for the help and links.

14

perhaps you should start here Vite Package Setup | CMS | Umbraco Documentation

15

It’s because getting a simple example up and running isn’t necessarily how you’d do it if creating a package.

The examples are more aligned to adding the extenstion to your site project, not creating a nuget package..

And as ever there are more than one way to skin a cat.. eg you can have it all in json manifests and js files in the wwwroot\app_plugins folder..
Next step up is vite building lit typescript files.. your manifest can move to cs code..
and then there is a package that could be inline files, or a razor class library with staticwebassets…

and your requirements could become a dashboard, with custom property editors etc… so then you might want to follow the opinionated-starter to have manifest bundles and modular comoponents that are all built togetther when the package is published..

Probably not making it any easier..

But in terms of the opionated-starter, once you have your development environment created from that template.. it;s the client/src folder..

image
image294×716 6.16 KB

and each component can be placed inside it’s own folder with a manifest, and then you add that manifest into the bundle.manifests.ts

image
image1034×318 44.4 KB

npm run build.. and the generated assets end up in the wwwroot/app_plugins/{your package name} folder..

image
image374×248 5.85 KB

and as it’s a razor class library once built those are automagically seen in your test site as it has a dependancy on the package project..

If you need api controllers for you package to fetch data etc.. then there are examples int he Contollers folder, and remember to add a composer if you need…
:slight_smile:

2 Likes
16

Thanks this info helps a lot

17

Thanks again for this, it has really helped me figure out the file mapping. I know undesrtand the client/public/umbraco-package.json is the same “app_plugins” json file talked about in the Umbraco docs. And I now understand that all the other stuff lives in the src folder as you talked about. I have succesfully made a new Umbraco Section and got it to show in the backoffice. With the understanding of the file structure I can now drive into the code and start work on my package. Apprecaite the explaination.

1 Like
18

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.