diff --git a/docs/en/Community-Articles/2024-11-25-Global-Assets/POST.md b/docs/en/Community-Articles/2024-11-25-Global-Assets/POST.md new file mode 100644 index 0000000000..ae8dfbd818 --- /dev/null +++ b/docs/en/Community-Articles/2024-11-25-Global-Assets/POST.md @@ -0,0 +1,156 @@ +# ABP Global Assets - New way to bundle JavaScript/CSS files in Blazor WebAssembly app + +We have introduced a new feature in the ABP framework to bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is called `Global Assets`. +With this feature, you don't need to run the `abp bundle` command to manually create/maintain the `global.js` and `global.css` files in your Blazor wasm app. + +## How Global Assets works? + +The new `Blazor wasm app` has two project. + +1. `MyProjectName` (ASP.NET Core app) +2. `MyProjectName.Client` (Blazor wasm app) + +The `MyProjectName` reference the `MyProjectName.Client` project, and will be the entry point of the application. which means the `MyProjectName` project will be the `host` project of the `MyProjectName.Client` project. + +The static/virtual files of `MyProjectName` can be accessed by the `MyProjectName.Client` project, so we can create dynamic global assets in the `MyProjectName` project and use them in the `MyProjectName.Client` project. + +## How it works in ABP? + +We have created a new package `WebAssembly.Theme.Bundling` for the theme `WebAssembly` module. and use `Volo.Abp.AspNetCore.Mvc.UI.Bundling.BundleContributor` to add `JavaScript/CSS` files to the bundling system. + +* LeptonXLiteTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule` +* LeptonXTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` +* LeptonTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonThemeBundlingModule` +* BasicTheme: `AbpAspNetCoreComponentsWebAssemblyBasicThemeBundlingModule` + +The new `ThemeBundlingModule` only depends on `AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule(new package)`, It's an `abstractions module` which only depends on `AbpAspNetCoreMvcUiBundlingAbstractionsModule`. + +We will get all `JavaScript/CSS` files on `OnApplicationInitializationAsync` method of `AbpAspNetCoreMvcUiBundlingModule` from bundling system and add them to `IDynamicFileProvider` service. after that, we can access the `JavaScript/CSS` files in the Blazor wasm app. + +## Use the Global Assets in the Blazor wasm app + +### MyProject + +Convert your `MyProject` project to integrate the `ABP module` system and depend on the `AbpAspNetCoreMvcUiBundlingModule` and `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule` + +* The `AbpAspNetCoreMvcUiBundlingModule` use to create the `JavaScript/CSS` files to virtual files. +* The `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule` use to add theme `JavaScript/CSS` to the bundling system. + +`Program.cs` file: + +```csharp +public class Program +{ + public async static Task Main(string[] args) + { + //... + + var builder = WebApplication.CreateBuilder(args); + builder.Host.AddAppSettingsSecretsJson() + .UseAutofac() + .UseSerilog(); + await builder.AddApplicationAsync(); + var app = builder.Build(); + await app.InitializeApplicationAsync(); + await app.RunAsync(); + return 0; + + //... + } +} +``` + +`MyProjectNameBlazorModule.cs` file: + +```csharp +[DependsOn( + typeof(AbpAutofacModule), + typeof(AbpAspNetCoreMvcUiBundlingModule), + typeof(AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule) +)] +public class MyProjectNameBlazorModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + //https://github.com/dotnet/aspnetcore/issues/52530 + Configure(options => + { + options.SuppressCheckForUnhandledSecurityMetadata = true; + }); + + // Add services to the container. + context.Services.AddRazorComponents() + .AddInteractiveWebAssemblyComponents(); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var env = context.GetEnvironment(); + var app = context.GetApplicationBuilder(); + + // Configure the HTTP request pipeline. + if (env.IsDevelopment()) + { + app.UseWebAssemblyDebugging(); + } + else + { + // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. + app.UseHsts(); + } + + app.UseHttpsRedirection(); + app.MapAbpStaticAssets(); + app.UseRouting(); + app.UseAntiforgery(); + + app.UseConfiguredEndpoints(builder => + { + builder.MapRazorComponents() + .AddInteractiveWebAssemblyRenderMode() + .AddAdditionalAssemblies(WebAppAdditionalAssembliesHelper.GetAssemblies()); + }); + } +} +``` + +`MyProjectName.csproj` file: + +```xml + + + + + + + +``` + +### MyProjectName.Client + +1. Remove the `global.JavaScript/CSS` files from the `MyProjectName.Client`'s `wwwroot` folder. +2. Refactor all BundleContributor classes that inherit from `IBundleContributor` to inherit from `BundleContributor` instead. +3. Remove the `AbpCli:Bundle` section from the `appsettings.json` file. + +### Check the Global Assets + +Run the `MyProject` project and check the `https://localhost/global.js` and `https://localhost/global.css` files. You will see the `JavaScript/CSS` files content from the Bundling system. + +![global](image.png) + +## GlobalAssets(AbpBundlingGlobalAssetsOptions) + +You can configure the JavaScript and CSS file names in the `GlobalAssets` property of the `AbpBundlingOptions` class. + +The default values are `global.js` and `global.css`. + +## Conclusion + +With the new `Global Assets` feature, you can easily bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is very useful for the Blazor wasm app, and it will save you a lot of time and effort. We hope you will enjoy this feature and use it in your projects. + +## References + +* [Virtual Files](https://docs.abp.io/en/abp/latest/Virtual-Files) +* [Bundle Contributors](https://abp.io/docs/latest/framework/ui/mvc-razor-pages/bundling-minification#bundle-contributors) +* [Global Assets Pull Request](https://github.com/abpframework/abp/pull/19968) + diff --git a/docs/en/Community-Articles/2024-11-25-Global-Assets/image.png b/docs/en/Community-Articles/2024-11-25-Global-Assets/image.png new file mode 100644 index 0000000000..347d54fe77 Binary files /dev/null and b/docs/en/Community-Articles/2024-11-25-Global-Assets/image.png differ