Trimming and lazy scripts

The most precise signal there is. Where the publish is trimmed (PublishTrimmed), the types ILLink left in the trimmed Bit.BlazorUI*.dll are the components the app can render, and the interop identifiers left in them the scripts it can call. It then supersedes the scan below - the same question, better answered - and a BitBlazorUIScan written out in the project is said to be unused in the build output.

Two exceptions. A server that hosts a WebAssembly client (the server of a Blazor Web App, whose static web assets carry the client's runtime) is answered by the scan instead: its trimmed assemblies are the server's, and say nothing of a component the client renders without prerendering it - and its PublishTrimmed does not turn the trimming on by itself. And a publish set up to be trimmed whose packages were not trimmed keeps the full bundles.

Where ILLink does not trim the publish - a Blazor Server app, a Blazor Web App's server, a WebAssembly app with PublishTrimmed off - the publish reads the app's own assemblies for the bit BlazorUI types they reference (a <BitButton> in a .razor file is a reference to Bit.BlazorUI.BitButton), and the untrimmed library assemblies for everything those types reach in turn. BitBlazorUIScan says how:

• TypeReferences - the default wherever a switch is on. Reads each assembly's type references, which name the namespace too: the precise mode.
• TypeNames - matches the library's type names against every name each assembly holds, without reading the reference tables. Coarser: an app with a class of its own called BitButton keeps that component too. It over-includes, never misses.
• None - reads nothing, and the full set is published - unless <BitBlazorUIComponent> items name what the app renders.

The assemblies read are the project's own and everything copied beside it, so the server of a Blazor Web App, which references its WebAssembly client, covers both. The platform's own assemblies (signed with Microsoft's or the .NET Foundation's keys) and the library's are passed over. When none of the assemblies read references the packages, they were not the app's: the publish keeps everything and says so (BITBLAZORUI002) rather than trim to nothing.

<PropertyGroup>
    <BitBlazorUIScan>TypeNames</BitBlazorUIScan> <!-- TypeReferences (default), TypeNames or None -->
</PropertyGroup>

• Its stylesheet, and the stylesheets of the components it renders - a stylesheet is kept for the component of its file name, and the parts of a component family (the many BitFc* types of BitFullCalendar) keep theirs.
• The scripts its code calls: every interop identifier ("BitBlazorUI.Callouts.toggle") keeps the script exporting it, with every script that one uses - across packages too, an Extras script keeping the core scripts it calls.
• The scripts it owns: a few scripts act on a component's markup without being called - the keyboard handling of BitNav, BitNavBar, BitButtonGroup, BitTag, BitTimeline, BitAppShell and BitDataGrid, the providers of BitMap - and are kept wherever that component is.
• The scripts its markup needs: a script acting on what markup says is kept wherever the app's code or markup says it - the theme on the bit-theme attributes, the claim of the Escape key on data-bit-esc, the arguments of the animation and transition events on onanimation* / ontransition*.
• The scripts every app needs: the version stamp and the keys every component relies on (the core's general and Utils.Keys, the Extras' general), kept even in an app that renders nothing.

Registering the services keeps nothing: AddBitBlazorUIServices() renders nothing, so it is not followed, and the modal and snack bar of an app that never uses them are left out. An app that injects a service - @inject BitModalService - names it, and that keeps what the service renders.

Whatever the signal, the app's own static markup and scripts - the .html, .htm, .js and .mjs static web assets of its projects, not the framework's under _framework - are read as text, and so are the string literals of its code. Their text counts like code of the app's own:

• an <html bit-theme-system> in a WebAssembly app's index.html keeps the theme's script;
• a class="bit-icon bit-icon--Add" keeps that glyph;
• a script of the app's own calling BitBlazorUI.PageVisibility.dispose(...) keeps that script - read however it is reached: window.BitBlazorUI..., globalThis.BitBlazorUI..., through optional chaining (BitBlazorUI.Theme?.onChange), or the namespace itself (const u = BitBlazorUI.Utils, which keeps every script adding to it).

A file the static web assets do not hold - a host page or a script outside the app's projects - is named with a <BitBlazorUIScanFile> item (next section).

The app's own stylesheets are not read. So an app that names theming nowhere - no bit-theme attribute in its markup, no theming API in its code - is published without the theme's script, and without the bit-theme="light" that script writes on <html> as it loads. The page still paints the light theme, which the stylesheets put on a bare :root, but a rule of the app's own selecting [bit-theme="light"] matches nothing: write the attribute on <html> yourself, which keeps the script as well, or keep it with <BitBlazorUIAsset Include="BitTheme" />.

No trimmed publish, the scan set to None and no component named: the full bundles are published. Names of scripts, stylesheets or icons alone trim nothing either - a list of glyphs says nothing of the components an app renders - while <BitBlazorUIComponent> items are a signal of their own: the whole of what the app renders.

Besides the bundles, every script also ships as an ES module of its own. Turn the lazy scripts on in the project you publish, and remove the <script> tags of the packages from your host page - the stylesheets stay:

<PropertyGroup>
    <BitBlazorUILazyScripts>true</BitBlazorUILazyScripts>
</PropertyGroup>

<!-- No longer needed: -->
<script src="_content/Bit.BlazorUI/scripts/bit.blazorui.js"></script>
<script src="_content/Bit.BlazorUI.Extras/scripts/bit.blazorui.extras.js"></script>
<script src="_content/Bit.BlazorUI.Legacy/scripts/bit.blazorui.legacy.js"></script>

The property drops the bundles from the app's static web assets and turns the mode on at runtime, through the Bit.BlazorUI.LazyScripts runtime switch and a one-line module initializer compiled into the project (runtime switches only reach a .NET 9 WebAssembly app and later; the initializer is what makes it hold on .NET 8, and needs C# 9 or later). Without the property, the modules, the boot modules and the initializers are dropped instead, so a bundle-mode app carries none of them.

• As the app starts, Blazor imports each package's JavaScript initializer (scripts/Bit.BlazorUI.lib.module.js), which imports the package's boot module: the scripts that act on the page without being called - the theme, the claim of the Escape key, the arguments of the animation and transition events, the keys every component relies on, and the Extras' window-size variables. This runs before Blazor renders anything, on a statically rendered page too.
• The first time a component calls into a script, the library imports its module (scripts/modules/Callouts.js), which imports the scripts of its package it uses; a script of the Extras using the core's has those imported first. Each module is imported once per WebAssembly app, Server circuit or WebView page, concurrent first calls share one import, and a failed import - a dropped connection, a 404 during a deploy - is tried again on the next call.
• A component owning a script that is called by nothing - the keyboard handling of BitNav, BitNavBar, BitButtonGroup, BitTag, BitTimeline, BitAppShell, BitDataGrid - loads it as it first renders what the script acts on: at once for most, once it is dismissible for a BitTag and once an item is clickable for a BitTimeline, so a plain tag or a read-only timeline downloads nothing. A script that fails to import (a lost connection, a 404 mid-deploy) costs the component those keys, never its render, and is imported again the next time it is asked for.
• A clean-up call into a script the page never ran - a dropdown disposed without ever opening - is skipped rather than downloading the script to release nothing.
• A synchronous call of WebAssembly imports its module before it runs.

The lazy scripts are trimmed the way the bundles are, from the same answer: only the modules of the scripts the app can reach are published, and the boot modules are written again with the boot scripts it keeps - an app that never themes anything does not boot the theme's script. The initializers are never changed (Blazor's own list names them by their fingerprint), and import the rewritten boot module. <BitBlazorUIIncludeScriptModules>true</BitBlazorUIIncludeScriptModules> written out in the project publishes every module instead.

Bit.BlazorUI: Bit.BlazorUI lazy script modules -> 19 of 53 (34 left out: nothing this app can run imports them).
Bit.BlazorUI: Bit.BlazorUI/scripts/bit.blazorui.boot.js -> 3 of 5 pieces, 101 of 163 bytes (-38%).

The same switch, for a host where the project cannot say it - it decides how the scripts load, never what is published:

builder.Services.AddBitBlazorUIServices(options =>
{
    options.LazyScripts = true;    // or false to insist on the bundles
    options.ContentPath = "https://cdn.example.com/_content/"; // only if the packages' assets are served elsewhere
    options.TrySingleton = false;  // the trySingleton argument of the plain overload
});

// Or directly:
BitBlazorUIScripts.UseLazyScripts();          // optionally with a content path
BitBlazorUIScripts.UseBundledScripts();
var lazy = BitBlazorUIScripts.LazyScriptsEnabled;

These are process-wide toggles, shared by every circuit of a Blazor Server app and meant to be set once at startup, before any component renders. ContentPath is the folder holding Bit.BlazorUI/ and the other packages' folders: a root-relative path or an absolute URL is taken as given, anything else is relative to the base href.

An app choosing the mode at runtime keeps both shapes, and renders its tags only for the bundles. A page that loads a package's bundle never runs that package's modules a second time: the bundle says it ran, and the initializer and every module leave their work to it - as long as the tag runs before Blazor's script starts the app, as it does after blazor.web.js without defer.

<PropertyGroup>
    <BitBlazorUIIncludeScriptBundle>true</BitBlazorUIIncludeScriptBundle>
    <BitBlazorUIIncludeScriptModules>true</BitBlazorUIIncludeScriptModules>
</PropertyGroup>

@if (BitBlazorUIScripts.LazyScriptsEnabled is false)
{
    <script src="_content/Bit.BlazorUI/scripts/bit.blazorui.js"></script>
}

• The theme on the very first paint: import the boot module from <head>, and Blazor's initializer finds it loaded: <script type="module" src="_content/Bit.BlazorUI/scripts/bit.blazorui.boot.js"></script>.
• A script of your own calling BitBlazorUI.* imports the module it calls first: await import('./_content/Bit.BlazorUI/scripts/modules/PageVisibility.js').
• A page rendered statically, with no interactive component, runs the boot scripts only - the keyboard handling a component loads as it renders needs it to be interactive.
• Blazor Hybrid loads the boot module from .NET too, before the first module of a package, so a host that runs no initializer still gets it.
• Assets on a CDN: set ContentPath to the folder holding the packages' folders.