Lazy Loading Assemblies in Blazor WebAssembly to Reduce Startup Size

Why lazy load assemblies in Blazor WebAssembly

Lazy loading moves selected DLLs out of the initial boot bundle so the first page download is smaller. The assembly is fetched only when a component that needs it is first rendered.

How to configure lazy loading

Mark the assembly as lazy in the project file and load it at runtime with the JS interop helper Blazor.WebAssembly.LoadAssemblyOnDemand.

Project file

<ItemGroup>
  <BlazorWebAssemblyLazyLoad Include='MyFeature.dll' />
</ItemGroup>

Component that triggers the load

@inject IJSRuntime JS

Load feature
@if (_featureLoaded)
{
    <MyFeatureComponent />
}
@if (_loading)
{
    <p>Loading…</p>
}

@code {
    private bool _featureLoaded;
    private bool _loading;

    private async Task LoadFeature()
    {
        _loading = true;
        try
        {
            await JS.InvokeVoidAsync('Blazor.WebAssembly.LoadAssemblyOnDemand', 'MyFeature.dll');
            _featureLoaded = true;
        }
        finally
        {
            _loading = false;
        }
    }
}

The MyFeature.dll must be referenced normally in the project so the compiler knows its types, but the BlazorWebAssemblyLazyLoad item tells the build system to emit it as a separate file.

Limits and common mistakes

• Do not mark the main application assembly (the one that contains the App component) as lazy; the runtime needs it to bootstrap the app.
• Avoid circular dependencies between a lazy assembly and the main bundle. If a type in the main project depends on a type that only exists in the lazy DLL, the runtime cannot resolve it until after the load, which may cause TypeLoadException.
• Always await the promise returned by LoadAssemblyOnDemand and show a loading indicator; otherwise the UI may appear blank while the DLL downloads.
• Lazy loading adds an extra network round‑trip and a small delay when the assembly is first needed. Measure the impact with the browser’s Network tab to ensure the trade‑off is worthwhile for your scenario.
• The feature requires .NET 6 or later; earlier SDKs do not understand the BlazorWebAssemblyLazyLoad item.

How to verify the setup

1. Build the Blazor WebAssembly project with .NET 7 (or later).
2. Open the app in a browser, open DevTools → Network, and reload the page. Verify that MyFeature.dll does not appear in the initial requests.
3. Click the 'Load feature' button. Observe a new request for MyFeature.dll and, after it completes, the MyFeatureComponent appears.
4. Check the console for any errors; a failed load will show a 'Failed to load resource' message indicating a mis‑configured lazy‑load item or wrong assembly name.