DEV Community

Kevin Jump
Kevin Jump

Posted on • Edited on

Battle scarred developer's guide to Umbraco v17 - Setup

#umbraco

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

In our previous post we've gotten our basic structure for our umbraco extension, but before we dive into code. there are a couple things i like to tweak.

You can choose to ignore this post!, these are my personal preferences for some of the more obscure bits of the setup, they are not required but they can make things a bit easier later on.

PackageManifestReader vs umbraco-package.json

umbraco-package.json

When you create a new umbraco extension you will get a umbraco-package.json file created in your client/public folder. this file defines the entry point for Umbraco to fetch and initialize your package

{
  "id": "MySuperPackage",
  "name": "MySuperPackage",
  "version": "0.0.0",
  "allowTelemetry": true,
  "extensions": [
    {
      "name": "My Super Package Bundle",
      "alias": "MySuperPackage.Bundle",
      "type": "bundle",
      "js": "/App_Plugins/MySuperPackage/my-super-package.js"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

and this works fine - but it has one or two issues.

1. the version number is just sitting there in a json file.
This can be a pain, because what happens when you release a new version ?well you either have to change this value or run some form of build script to change it for you.

2. the JavaScript file never changes and might be cached between releases
Because the main JavaScript file is in this file it doesn't change between releases, this means if someone updates your package to a new version this file URL is still the same and their browser might not fetch the newer version from the server.

IPackageManaifestReader

Another alternative is to use a IPackageManifestReader (https://dev.to/skttl/server-side-registering-of-package-manifest-in-umbraco-14-49go by @skttl) which allows you to register your package via your backend code (see DoStuffPackageManifestReader.cs

public Task<IEnumerable<PackageManifest>> ReadPackageManifestsAsync()
{
  var version = Assembly.GetAssembly(typeof(DoStuffPackageManifestReader))?
   .GetName()
   .Version?.ToString() ?? "1.0.0";

  return Task.FromResult<IEnumerable<PackageManifest>>(new[]
  {
    new PackageManifest
    {
      Id = "DoStuff.Client",
      Name = "DoStuff with Umbraco client",
      AllowTelemetry = true,
      Version = version,
      Extensions = [
        new {
          name = "DoStuff Client Bundle",
          alias = "DoStuff.Client.Bundle",
          type = "bundle",
          js = "/App_Plugins/DoStuffClient/do-stuff-client.js?v=" + version
        }
     ]
   }
  });
}
Enter fullscreen mode Exit fullscreen mode

You can see there is a little bit more code here but the basic information is the same as the umbraco-package.json file.

The key difference is we can fetch the version from the running assembly(dll).

When you build your NuGet packages of your extension the version will be stamped on the dll's in the package by NuGet's pack process. and once its there the code in your IPackageManifestReader will use that version value to update your package version and add it to the end of the JavaScript file's URL. meaning for each new version the browser will fetch the file again.

You need to remember to register your package manifest in a composer

builder.Services
  .AddSingleton<IPackageManifestReader, DoStuffPackageManifestReader>();

Entry points Auth.

Another change that we will go into more detail in, when we talk about entry points and APIs is the code for setting up the authentication between sites.

if you use the opinionated starter kit (or the umbraco-extension with the `-ex' flag) you will get the skeleton of the code for communicating with the server from your font end code.

`ts
_host.consumeContext(UMB_AUTH_CONTEXT, async (authContext) => {
// Get the token info from Umbraco
const config = authContext?.getOpenApiConfiguration();

client.setConfig({
auth: config?.token ?? undefined,
baseUrl: config?.base ?? "",
credentials: config?.credentials ?? "same-origin",
});
});
`

This is fine and it works - but from a bit of experience there is another bit you can add, that helps to keep things fresh should you have the browser open all day

ts
// client interceptor will get the latest token for the auth
// context for a request, so if the token has been refreshed
// since we first got it, we'll still have a valid token.
client.interceptors.request.use(async (request, _options) => {
const token = await authContext?.getLatestToken();
request.headers.set("Authorization",Bearer ${token});
return request;
});

A client interceptor will run when the requests are fired and just make sure you have the latest token from the user send over as part of the request.

Again this isn't something you have to do, everything works fine in the examples, this just smooths the odd edge I have seen during development.

Top comments (0)