Substantive.Blazor.JSInterop

Utilities for bridging .NET and browser APIs in Blazor applications. The library ships a set of opinionated services that simplify dynamically loading JavaScript, CSS, and other assets at runtime while keeping Blazor Server and Blazor WebAssembly hosting models in sync.

Why this library?

• Consistent DOM loading – IDomFileInjector abstracts both JSHost (WASM) and IJSRuntime (Server) pipelines, so component code stays identical regardless of where it runs.
• Security-first defaults – optional attributes (integrity, crossorigin, referrerpolicy, nonce, fetchpriority) map directly to the generated DOM nodes, reducing CSP and mixed-content regressions.
• Tenant/feature isolation – scripts, styles, or media can be injected when a component activates and removed when it disposes, minimizing bundle size and side effects.
• Deterministic cleanup – optional tag identifiers let you remove previously injected assets without tracking the original URIs, which is useful for multi-tenant layouts and dynamic feature toggles.
• Typed interop surface – TypeScript helpers (wwwroot/src/DynamicFileLoader.ts) and the bundled JS deliver a narrowly scoped API focused on asset management.

Getting started

1. Reference the project/package from your Blazor application.

2. Register the injector for the current hosting model in Program.cs:

   if (OperatingSystem.IsBrowser())
   {
       builder.Services.AddSingleton<IDomFileInjector, DomFileInjectorJSHost>();
   }
   else
   {
       builder.Services.AddSingleton<IDomFileInjector, DomFileInjectorJSRuntime>();
   }
   

3. Inject and use the service inside a component:

   @inject IDomFileInjector DomFileInjector
   @implements IAsyncDisposable
   
   protected override async Task OnAfterRenderAsync(bool firstRender)
   {
       if (firstRender)
       {
           await DomFileInjector.LoadJavaScriptFileAsync(
               scriptSrc: "https://cdn.example.com/widgets.js",
               scriptType: "module",
               integrity: "sha384-...",
               crossOrigin: "anonymous",
               referrerPolicy: "strict-origin-when-cross-origin",
               nonce: cspNonceFromServer,
               fetchPriority: "high",
               tag: "widgets-lib");
   
           await DomFileInjector.LoadCSSFileAsync(
               src: "https://cdn.example.com/widgets.css",
               media: "(min-width: 768px)",
               tag: "widgets-style");
       }
   }
   
   public async ValueTask DisposeAsync()
   {
       await DomFileInjector.UnloadJavaScriptFileByTagAsync("widgets-lib");
       await DomFileInjector.UnloadCSSFileByTagAsync("widgets-style");
   }
   

Features

Development workflow

1. Edit TypeScript in wwwroot/src.

2. Bundle using the repo’s configured bundler (Rspack). Running dotnet build regenerates wwwroot/dist/js/DynamicFileLoader.bundle.js via the existing targets.

3. Run tests/build from the repo root:

   dotnet build
   

Tag-based unloading cheat sheet