{"id":20409419,"url":"https://github.com/jsakamoto/toolbelt.blazor.routablelazyassemblyloader","last_synced_at":"2025-04-12T15:45:12.004Z","repository":{"id":187845041,"uuid":"677584395","full_name":"jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader","owner":"jsakamoto","description":"A router component and a service to simplify lazy assembly loading and to avoid flickering of initial loading on pre-rendered Blazor Wasm apps.","archived":false,"fork":false,"pushed_at":"2023-08-12T08:38:58.000Z","size":2954,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T10:11:37.350Z","etag":null,"topics":["blazor","blazor-wasm","blazor-webassembly","lazy-loading","pre-rendering","prerendering"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsakamoto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-12T01:13:01.000Z","updated_at":"2024-12-26T21:08:22.000Z","dependencies_parsed_at":"2023-08-12T10:51:13.766Z","dependency_job_id":null,"html_url":"https://github.com/jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader","commit_stats":null,"previous_names":["jsakamoto/toolbelt.blazor.routablelazyassemblyloader"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.RoutableLazyAssemblyLoader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.RoutableLazyAssemblyLoader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.RoutableLazyAssemblyLoader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsakamoto%2FToolbelt.Blazor.RoutableLazyAssemblyLoader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsakamoto","download_url":"https://codeload.github.com/jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248591052,"owners_count":21129950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blazor","blazor-wasm","blazor-webassembly","lazy-loading","pre-rendering","prerendering"],"created_at":"2024-11-15T05:41:35.231Z","updated_at":"2025-04-12T15:45:11.983Z","avatar_url":"https://github.com/jsakamoto.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blazor Routable Lazy Assembly Loader [![NuGet Package](https://img.shields.io/nuget/v/Toolbelt.Blazor.RoutableLazyAssemblyLoader.svg)](https://www.nuget.org/packages/Toolbelt.Blazor.RoutableLazyAssemblyLoader/)\n\n## Summary\n\nThis service and router component allows you to simplify lazy assembly loading for your Blazor WebAssembly app. \n\nMoreover, this library allows us to **avoid flickering** when first loading a page which is contained in a lazy loading assembly on pre-rendered Blazor WebAssembly apps.\n\n\n## Supported Blazor versions\n\nThis library suppots ASP.NET Core Blazor WebAssembly version 6.0 or later.\n\n## Basic Usage\n\n### 1. Configure the project file of your Blazor WebAssembly app to enable lazy assembly loading\n\nPlease make sure the project file (.csproj) of your Blazor WebAssembly app is configured to enable lazy assembly loading. Please refer to the \"Project file configuration\" section of the following document for details.\n\n_[\"Lazy load assemblies in ASP.NET Core Blazor WebAssembly | Microsoft Learn\"](https://learn.microsoft.com/aspnet/core/blazor/webassembly-lazy-load-assemblies#project-file-configuration)_\n\nQuoted from the above document below.\n\n\u003e Mark assemblies for lazy loading in the app's project file (.csproj) using the `BlazorWebAssemblyLazyLoad` item. Use the assembly name with the `.dll` extension. The Blazor framework prevents the assembly from loading at app launch.\n\u003e\n\u003e ```xml\n\u003e \u003cItemGroup\u003e\n\u003e   \u003cBlazorWebAssemblyLazyLoad Include=\"{ASSEMBLY NAME}.dll\" /\u003e\n\u003e \u003c/ItemGroup\u003e\n\u003e ```\n\u003e\n\u003e The `{ASSEMBLY NAME}` placeholder is the name of the assembly. The `.dll` file extension is required.\n\u003e\n\u003e Include one `BlazorWebAssemblyLazyLoad` item for each assembly. If an assembly has dependencies, include a BlazorWebAssemblyLazyLoad entry for each dependency.\n\n\n### 2. Installation and Registration\n\n**Step.1** Install the library via NuGet package, like this.\n\n```shell\ndotnet add package Toolbelt.Blazor.RoutableLazyAssemblyLoader\n```\n\n**Step.2** Register the \"RoutableLazyAssemblyLoader\" service into the DI container, including the mapping of \"requested URL path -\u003e assembly names to be loaded\".\n\n```csharp\n// 📄Program.cs\nusing Toolbelt.Blazor.Extensions.DependencyInjection; // 👈 1. Add this line\n...\n// 👇 2. Add this code\nbuilder.Services.AddRoutableLazyAssemblyLoader(path =\u003e path switch\n{\n    // ⚠️ Please implement your own logic to return the list of lazy assembly names \n    //    corresponding to each requested URL path.\n    \n    // This sample code shows that the routable Razor component required for the page\n    // \"https://.../counter\" lives in the \"CounterPage.dll\" lazy loading assembly.\n    \"counter\" =\u003e new[] { \"CounterPage.dll\" },\n\n    // If nothing to load, just return null.\n    _ =\u003e null\n});\n...\n```\n\n### 3. Use the `\u003cLazyAssemblyLoadableRouter\u003e` component instead of `\u003cRouter\u003e` component\n\nReplace the `\u003cRouter\u003e` component with `\u003cRoutableLazyAssemblyLoader\u003e` component in your `App.razor` file.\n\n```html\n@* 📄App.razor *@\n\n@using Toolbelt.Blazor.Components // 👈 1. Add this line\n...\n// 👇 2. Replace the \u003cRouter\u003e component with \u003cRoutableLazyAssemblyLoader\u003e component.\n\u003cLazyAssemblyLoadableRouter AppAssembly=\"@typeof(App).Assembly\"\u003e\n    \u003cFound Context=\"routeData\"\u003e\n        \u003cRouteView RouteData=\"@routeData\" DefaultLayout=\"@typeof(MainLayout)\" /\u003e\n        \u003cFocusOnNavigate RouteData=\"@routeData\" Selector=\"h1\" /\u003e\n    \u003c/Found\u003e\n    \u003cNotFound\u003e\n        \u003cPageTitle\u003eNot found\u003c/PageTitle\u003e\n        \u003cLayoutView Layout=\"@typeof(MainLayout)\"\u003e\n            \u003cp role=\"alert\"\u003eSorry, there's nothing at this address.\u003c/p\u003e\n        \u003c/LayoutView\u003e\n    \u003c/NotFound\u003e\n\u003c/LazyAssemblyLoadableRouter\u003e\n```\n\n### 4. Run it!\n\nAfter the above steps, you can run your Blazor WebAssembly app as usual. In the sample code above, the \"CounterPage.dll\" lazy loading assembly won't be loaded initially and will be loaded when the user navigates to the \"/counter\" page.\n\n## Prevent flickering on 1st time rendering of lazy loaded pages in pre-rendered Blazor WebAssembly apps.\n\nIf you use the pre-rendering feature of Blazor WebAssembly, you may notice that the lazy-loaded page flickers when it is first rendered. This is because the lazy-loaded page is rendered twice. The first time is when the page is rendered on the server side, and the second time is when the page is rendered on the client side. Usually, the time gap between 1st rendering and 2nd rendering will be almost 0, so nobody may see it flickers. However, when the page is lazy loaded, it might take a few hundred milliseconds to 2nd rendering because Blazor has to fetch the lazy assembly. That means a blank page will be shown during the loading of the lazy assembly. That is the reason for the flickering of the page in this scenario.\n\nFortunately, this library provides a solution to this problem. The solution is to preload the lazy assembly for the current URL before starting rendering. This library provides an extension method for the `WebAssemblyHost` class to do this. Please call the `PreloadRoutableLazyAssemblyAsync` extension method before calling the `RunAsync` method of the `WebAssemblyHost` instance, as below.\n\n```csharp\n// 📄Program.cs\n...\nvar host = builder.Build();\n// 👇 Preload lazy assembly for the current URL before starting rendering\n//    by calling the \"PreloadRoutableLazyAssemblyAsync\" extension method.\nawait host.PreloadRoutableLazyAssemblyAsync();\nawait host.RunAsync();\n```\n\nAfter implementing the above code, flickering will be prevented.\n\n![Movie - Before and After](https://raw.githubusercontent.com/jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader/main/.assets/before-after-movie.gif)\n\n## Acknowledgements\n\nThe idea to prevent flickering on 1st time rendering of lazy loaded pages in pre-rendered Blazor WebAssembly apps was **provided by [Connor Hallman](https://github.com/biegehydra)** in [his pull request #32](https://github.com/jsakamoto/BlazorWasmPreRendering.Build/pull/32) for the [\"BlazorWasmPreRendering.Build\" NuGet package project](https://github.com/jsakamoto/BlazorWasmPreRendering.Build). And when I asked him that may I instantiate his idea to a NuGet package by me, he readily agreed. Thank you, Connor, for your contributions!\n\n## Release Note\n\n[Release notes](https://github.com/jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader/blob/main/RELEASE-NOTES.txt)\n\n## License\n\n[Mozilla Public License Version 2.0](https://github.com/jsakamoto/Toolbelt.Blazor.RoutableLazyAssemblyLoader/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsakamoto%2Ftoolbelt.blazor.routablelazyassemblyloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsakamoto%2Ftoolbelt.blazor.routablelazyassemblyloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsakamoto%2Ftoolbelt.blazor.routablelazyassemblyloader/lists"}