[V15] Updated dotnet template for Umbraco Packages with Bellisima

[warrenbuckley]

Summary

• Renames umbraco-package to umbraco-extension
• Adds tooling for Vite, TypeScript and similar that the Umbraco HQ core team uses to help align with tutorials etc

This PR is to rework & reopen the work that @leekelleher done from the previous years community teams day
#14975

---

Install Command

dotnet new install umbraco-extension --name TestingProject

Example usage

# Create solution
dotnet new sln --name "MyProject"

# Create Umbraco Website Project
dotnet new umbraco --name "MyProject.Website" --friendly-name "Administrator" --email "[email protected]" --password "1234567890" --development-database-type SQLite

# Add the Website project to the SLN
dotnet sln add "MyProject.Website"

# Create the extension project
dotnet new umbraco-extension --name "MyProject.Extensions"

# Add the extension project to the SLN
dotnet sln add "MyProject.Extensions"

# Add the extension project as a reference
dotnet add ".\MyProject.Website\MyProject.Website.csproj" reference ".\MyProject.Extensions\MyProject.Extensions.csproj"

# Change Directory to JS clientside
cd ".\MyProject.Extensions\Client"

# NPM install (Remember you need to be on node 20.0+)
npm install

# Build TypeScript & compile into MyProject.Extensions RCL
npm run build

# Move back upto root of project
cd "..\..\"

# dotnet run (Which does a build)
dotnet run --project "MyProject.Website"

[github-actions]

Hi there @warrenbuckley, thank you for this contribution! 👍

While we wait for one of the Core Collaborators team to have a look at your work, we wanted to let you know about that we have a checklist for some of the things we will consider during review:

• It's clear what problem this is solving, there's a connected issue or a description of what the changes do and how to test them
• The automated tests all pass (see "Checks" tab on this PR)
• The level of security for this contribution is the same or improved
• The level of performance for this contribution is the same or improved
• Avoids creating breaking changes; note that behavioral changes might also be perceived as breaking
• If this is a new feature, Umbraco HQ provided guidance on the implementation beforehand
• 💡 The contribution looks original and the contributor is presumably allowed to share it

Don't worry if you got something wrong. We like to think of a pull request as the start of a conversation, we're happy to provide guidance on improving your contribution.

If you realize that you might want to make some changes then you can do that by adding new commits to the branch you created for this work and pushing new commits. They should then automatically show up as updates to this pull request.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂

[LottePitcher]

If you were extending/customising the backoffice of a project in v13 and earlier, you could just add your code into a folder in App_Plugins - there was no need for front-end build steps as you deployed the source files. This package template really was a (very simple) start to people building actual packages: it wasn't needed by people looking to just customise a specific Umbraco backoffice.

In v14+ you definitely do not want to have your source files for your own extensions in App_Plugins, and so I think that the template being proposed here is arguably a template for extending the backoffice, not for building a package.

So in light of that would renaming the template from umbracopackage to umbracoextension make sense? e.g.

dotnet new umbracoextension -n MyWebsite.Extensions

It would also differentiate this template from community templates that are designed for developing packages - that come with test sites, and a head-start on publishing to nuget etc. Whereas this core template is showing good practise for extending the backoffice. That extension might turn into a package to be distributed, but equally it might just be for a specific Umbraco project.

[warrenbuckley]

@LottePitcher the rename of the dotnet new template makes total sense to me.
One thing I am unclear on though from your comments is that should this template not do the TypeScript, Vite stuff and just be an RCL that has an umbraco-package.json file and use vanilla JS to avoid tooling problems or have I misunderstood?

[LottePitcher]

@warrenbuckley I think the tooling setup (Vite etc) is still a good idea as it gets you started a good way, and it's the approach that backend devs with less front-end experience will need more help with. I don't think anyone would recommend using VanillaJS unless you were just building something incredibly simple.

[warrenbuckley]

@umbraco/packages-team take a look at this PR please gang

[warrenbuckley]

I would also appreciate any opinions from the front end gang @leekelleher @nielslyngsoe @madsrasmussen @iOvergaard as well to ensure this is a-okay or needs stuff doing.

[jemayn]

Looks like both would work, but the example you have in your entry point file looks more like the bundle type than the backofficeEntryPoint type. Maybe someone on the Backoffice team has thoughts on this.

[warrenbuckley]

AFAIK Bundles is for registering manifests only, where an entrypoint you may do other logic inside it.
Such as to do the AUTH stuff with the C# OpenAPI spec or perhaps unregister/exclude extensions etc...

But lets wait for someone from the frontend core crew to chime in.

[warrenbuckley]

@nielslyngsoe @iOvergaard any thoughts ?

[nielslyngsoe]

Hi @warrenbuckley
I would say use the EntryPoint for what the entry point is needed for, but do not use it to registere more manifests. For that its better to use the Bundle.
Main reason begin a bundle knows the extensions it registres. Meaning if later and that could be milliseconds later, it knows how to unregisters it self. Useful if someone decides to unregister it.

So my opinion would be, in order to be the most correct as you can, then make both, one bundle and one entry point so people can see how the can execute code up front and use the bundle to lead the way for more extensions. :-)

[iOvergaard]

You have got the facts correct, @warrenbuckley. I would recommend sticking with the backofficeEntryPoint.

[warrenbuckley]

Seems overkill don't you think @nielslyngsoe & @iOvergaard to have the following and is more concepts to teach/get across unless this really is THE WAY

umbraco-package.json -> backofficeEntryPoint -> bundle

[nielslyngsoe]

Just to confirm you got everything right in your above comment. :-)

But I would still suggest this style:
umbraco-package.json -> bundle -> backofficeEntryPoint

Meaning anything additionally begin added would go to the bundle:
umbraco-package.json -> bundle -> dashboard

In this way avoiding to use the entry-point to do registration of other extension-manifest. Meaning the entry-point is purely needed for the act of running some JS code. Then if people then dont need to run code, they can ignore that specific type.

I think that is the most correct style.

This is based on an interest in registering extensions via JS. If you dont mind doing it in JSON. Then you can skip the bundle, to do additional registrations as of the umbraco-package.json.

But my point begin, I'm not a fan of show casing people that they should registere extensions by calling extensionRegistry.registerMany

[iOvergaard]

Would be good to set the BASE_DIR option somewhere here (can't remember where). It ensures that assets imported through Vite's public folder have the correct path applied.

[warrenbuckley]

The only thing used for the public folder atm is for the umbraco-package.json
If you have an example @iOvergaard I will gladly add it in 😄

[iOvergaard]

If you add this to the config:

  base: '/App_Plugins/MyLib'

Full example:

export default defineConfig({
  build: {
    lib: {
      entry: ['src/main.ts'],
      formats: ['es'],
    },
    sourcemap: true,
    outDir: '../wwwroot/App_Plugins/MyLib',
    emptyOutDir: true,
    rollupOptions: {
      external: [/@umbraco-cms\/backoffice\//],
    },
  },
  base: '/App_Plugins/MyLib',
});

Then stuff like this works:

<img src="/logo.jpg" />

and this

import imageUrl from '/logo.jpg';

<img src=${imageUrl} />

[iOvergaard]

You could add a build step somewhere here to ensure frontend assets are built on startup. There are various ways of checking if they need to be rebuilt.

  <PropertyGroup>
    <ClientAssetsDirectory Condition="'$(ClientAssetsDirectory)' == ''">client/</ClientAssetsDirectory>
    <ClientAssetsRestoreInputs Condition="'$(ClientAssetsRestoreInputs)' == ''">$(ClientAssetsDirectory)package-lock.json;$(ClientAssetsDirectory)package.json</ClientAssetsRestoreInputs>
    <ClientAssetsRestoreOutputs Condition="'$(ClientAssetsRestoreOutputs)' == ''">$(ClientAssetsDirectory)node_modules;package-lock.json</ClientAssetsRestoreOutputs>
    <ClientAssetsRestoreCommand Condition="'$(ClientAssetsRestoreCommand)' == ''">npm install</ClientAssetsRestoreCommand>
    <ClientAssetsBuildCommand Condition="'$(ClientAssetsBuildCommand)' == ''">npm run build</ClientAssetsBuildCommand>
    <ClientAssetsBuildOutputParameter Condition="'$(ClientAssetsBuildOutputParameter)' == ''">--outDir</ClientAssetsBuildOutputParameter>
    <ClientAssetsRestoreInputs>$(MSBuildProjectFile);$(ClientAssetsRestoreInputs)</ClientAssetsRestoreInputs>
    <ClientAssetsOutputPath>wwwroot/App_Plugins/MyLib/</ClientAssetsOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <ClientAssetsInputs Include="$(ClientAssetsDirectory)**" Exclude="$(DefaultItemExcludes)" />
  </ItemGroup>

  <Target Name="NpmInstall" Inputs="$(ClientAssetsRestoreInputs)" Outputs="$(ClientAssetsDirectory)package-lock.json;$(ClientAssetsDirectory)node_modules/.install-stamp">
    <Message Importance="high" Text="Running $(ClientAssetsRestoreCommand)..." />
    <Exec Command="$(ClientAssetsRestoreCommand)" WorkingDirectory="$(ClientAssetsDirectory)" />
    <Touch Files="$(ClientAssetsDirectory)node_modules/.install-stamp" AlwaysCreate="true" />
  </Target>

  <Target Name="NpmRunBuild" DependsOnTargets="NpmInstall" BeforeTargets="AssignTargetPaths" Inputs="@(ClientAssetsInputs)" Outputs="$(IntermediateOutputPath)client/assets/build.complete.txt">
    <Exec Command="$(ClientAssetsBuildCommand) -- $(ClientAssetsBuildOutputParameter) ../$(ClientAssetsOutputPath)" WorkingDirectory="$(ClientAssetsDirectory)" />

    <Message Importance="high" Text="Linking client assets to wwwroot..." />

    <ItemGroup>
      <_ClientAssetsBuildOutput Include="$(ClientAssetsOutputPath)**" />

      <FileWrites Include="@(_ClientAssetsBuildOutput)" />
      <FileWrites Include="$(IntermediateOutputPath)client/assets/build.complete.txt" />
    </ItemGroup>

    <WriteLinesToFile File="$(IntermediateOutputPath)client/assets/build.complete.txt" Lines="@(_ClientAssetsBuildOutput)" />
  </Target>

I took this directly from a test project of mine. It writes the file list to build.complete.txt and checks up against that for any changes the next time you build the .NET project. It will also optionally install npm deps again if the lockfile has changed. Hope it still works :-)

[warrenbuckley]

Yeh I am in two minds about dotnet doing magical builds of client side assets and running node/npm stuff
As its kinda voodoo magic that magically just builds it from Rider, VS or dotnet CLI

It doesn't help teach how the client-side assets are built and put into the RCL, but if people have to explicitly run node/npm run commands then they are more conscious of what is going on and how its put together.

[warrenbuckley]

Curious to hear from peeps in the team who are building/implementing stuff such as
@nathanwoulfe @mattbrailsford @leekelleher @ronaldbarendse in packages