Load CSS files in Bellissima (V14+)

[iOvergaard]

From time to time, you will need to load global CSS files into the Backoffice. This is useful if you need to set global CSS variables or even overwrite some of Umbraco's own CSS variables.

ℹ️ This is different from the CSS needed for Web Components, where a bundler most likely will take care of inlining your styles or making sure to load the CSS files for you.

As of writing this, the only way to mount a raw CSS file into the Backoffice is to register an extension of type "backofficeEntryPoint" and in its JavaScript module file create a link tag and add it to the document:

umbraco-package.json

{
    "$schema": "../../MyPackage.Website/umbraco-package-schema.json",
    "id": "myPackage",
    "name": "My Package",
    "allowPackageTelemetry": true,
    "version": "1.0.0",
    "extensions": [
        {
          "name": "My Package EntryPoint",
          "alias": "mypackage.entrypoint",
          "type": "backofficeEntryPoint",
          "js": "/App_Plugins/MyPackage/entrypoint.js"
        }
      ]
}

entrypoint.js

const myCss = document.createElement('link')
myCss.rel = 'stylesheet'
myCss.href = '/App_Plugins/MyPackage/mycss.css'

document.head.appendChild(myCss)

There are various ways where we can make this easier for the developer. For one, we can add a function that lets you specify the CSS more directly and the Backoffice can load it either before or after itself is loaded:

function addCss(href: string, beforeOrAfter: 'before' | 'after') {}

This still requires the developer to register an entrypoint, however. It also does not solve another issue, which could best be described as "load order" or "weight" where you might want to inject a stylesheet into a very specific order due to CSS specificity, where the order matters. The previous Backoffice (Belle) supported a css array in its package.manifest file where you could load CSS files. They would be lazy-loaded and thus not necessarily loaded in any known order.

I think we need some resemblance of the css array introduced in Bellissima, but the theme I want to discuss here is what people need. Based on this comment by Anders Bjerner, we could get the idea that an extension type of "CSS" with some kind of weight/order would solve some needs. This is certainly doable, but what would the format look like? Where does one register a CSS file?

[abjerner]

My use case that led me to create the issue was adding some branding to the backoffice - e.g. to set my own values for some of Umbraco's CSS variables.

When adding a custom <link /> element via a backoffice entry point, the element is added too late, and the user may experience that the UI is "blinking" or that they visually can see a small delay until the custom stylesheet is loaded.

I'm not entirely sure how the proposed addCss function would work. If one is supposed to call it from a backoffice entry point, wouldn't it still bee too late to add anything before Umbraco's stylesheets?

I'm not a frontender, so the new backoffice is a bit out of my comfort zone, but I think that a new css extension could address this use case - including settings a specific weight - either by a number or a specific "time" (or both).

[iOvergaard]

Yes, the addCss function is just to wrap the JavaScript currently needed to do that. You might experience blinking depending on what you change, so it's not the solution for everything. It would essentially just help the developer to add a link tag somewhere in the application.

[warrenbuckley]

Could this not be scanned to check for any globalCSS extensions so when you write the DOM for the HTML page for the main umb-app backoffice for the first time that it will load the CSS files there from the server.

Then any extensions of globalCss that are loaded/added after the initial boot will have to have the CSS injected/created with a link element and may cause a flash of unstyled content

[iOvergaard]

Could this not be scanned to check for any globalCSS extensions so when you write the DOM for the HTML page for the main umb-app backoffice for the first time that it will load the CSS files there from the server.

Out of principle, we don't scan the "extensions" list on the server because it belongs to the Backoffice client. That isn't to say we can't add a "globalCss" extension type, it would just be handled by the Backoffice client instead.

[warrenbuckley]

Hi @iOvergaard 👋
For me the simplest way to register a CSS file would be in the main umbraco-package.json file, where we can register all manifests in this file.

For me I would have the approach of this JSON file containing two entries, one for the main entrypoint JS that can then register other manifests as per normal, and the second entry to be for the CSS file I want to register as a global CSS and its path, along with weight. With the weight I can determine the order that the CSS files load in then.

{
    "$schema": "../../MyPackage.Website/umbraco-package-schema.json",
    "id": "myPackage",
    "name": "My Package",
    "allowPackageTelemetry": true,
    "version": "1.0.0",
    "extensions": [
        {
          "name": "My Package EntryPoint",
          "alias": "mypackage.entrypoint",
          "type": "backofficeEntryPoint",
          "js": "/app_plugins/MyPackage/MyPackage.js"
        },
        {
          "name": "My Custom CSS",
          "alias": "my.custom.css",
          "type": "globalCss",
          "css": "/app_plugins/MyPackage/css/custom.css",
          "weight": -1
        }
      ]
}

[iOvergaard]

Would Umbraco's CSS have a weight of zero, or do you have any thoughts on how to add something before or after Umbraco's CSS? I'd imagine "position": "head" would mean that the <link /> element is just appended otherwise.

Yes, I would think Umbraco's have weights of 100, 200, 300, and so on, so you can inject your styles in between ours. I believe we currently load two files, one for the backoffice and one for the UI library.

[warrenbuckley]

As long as they appear in the extensions table, then we can see what value/weights are set for the CSS files and then set our own weights accordingly to load before or after as needed.

My naivety does it really matter if the CSS is loaded in the Head or the Body ?

[iOvergaard]

My naivety does it really matter if the CSS is loaded in the Head or the Body ?

Probably not. You would want global CSS to be loaded before any HTML anyway. Maybe it could be an advantage of loading some of it as "preload", but that is probably more relevant for websites where FCP matters.

<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">

[deanleigh]

As long as they appear in the extensions table, then we can see what value/weights are set for the CSS files and then set our own weights accordingly to load before or after as needed.

My naivety does it really matter if the CSS is loaded in the Head or the Body ?

In short yes otherwise you have render blocking, fouc, reflow, performance issues etc… and lots more.
Something I have been experimenting with is exposing parts of web components styling in different ways including data attributes and CSS custom properties.
I haven't looked in detail at how UUI has been marked up but if there is a consistent naming convention adding to or over-writing the global styles should not cause too many issues.

[enkelmedia]

Personally, I have not needed to load any CSS "from the server" for any of my packages yet. I'm using the "hack" that @iOvergaard shows at the start of the discussion to set my own CSS variables so I have no first-hand experience with the "flickering" that might be caused by loading global CSS that overwrites Umbraco's variables.

I would vote for the proposal of adding a new CSS-array to the umbraco-package.json file as this would give the ultimate flexibility - any other approach could suffer from the issues with extensions getting loaded "too slow" causing blinking etc.