kb(common): Add KB for cache busting (#2281)

* kb(common): Add KB for cache busting * polishing * Update knowledge-base/common-browser-cache-buster.md * Update knowledge-base/common-browser-cache-buster.md
telerik · Jul 30, 2024 · 29ccedc · 29ccedc
1 parent 7234fcc
commit 29ccedc
Show file tree

Hide file tree

Showing 8 changed files with 102 additions and 13 deletions.
diff --git a/common-features/cdn.md b/common-features/cdn.md
@@ -102,7 +102,7 @@ The CDN hosts the [JavaScript (JSInterop) file of Telerik UI for Blazor]({%slug
 The benefits of using a CDN in Blazor apps are:
 
 * Possible performance gains in the application loading time. Blazor apps are single page applications and browsers rely on cache by default, so this benefit is marginal and relates only to users that open the application for the first time.
-* Avoidance of browser caching issues after component version upgrades. The CSS and JS files change with every component version, and so do the CDN URLs. This URL change guarantees that browsers will reload the static assets.
+* Avoidance of [browser caching issues after component version upgrades]({%slug common-kb-browser-cache-buster%}). The CSS and JS files change with every component version, and so do the CDN URLs. This URL change guarantees that browsers will reload the static assets.
 
 The drawbacks of using a CDN are:
 

diff --git a/getting-started/what-you-need.md b/getting-started/what-you-need.md
@@ -144,6 +144,8 @@ The Telerik UI for Blazor components require a [theme stylesheet](#css-theme) an
 
 To use static CSS and JS assets from the NuGet package in a project, make sure that the project has [`app.UseStaticFiles();` in its `Program.cs`](https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-8.0&tabs=visual-studio#consume-content-from-a-referenced-rcl) file. This is true by default.
 
+You can also [add the Telerik UI for Blazor version number to the CSS and JavaScript file URLs to prevent browser caching during version upgrades]({%slug common-kb-browser-cache-buster%}).
+
 ### CSS Theme
 
 Register the [Telerik theme stylesheet]({%slug themes-built-in%}) in the `<head>` of the web page. Add the theme before the application stylesheet and the [CSS isolation stylesheet](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/css-isolation). This CSS file order lets you [override Telerik theme styles]({%slug themes-override%}) more easily, if necessary.
@@ -263,5 +265,6 @@ The Blazor application is ready to use Telerik components.
 
 * [Automated MSI installer]({%slug installation/msi%})
 * [ZIP archive]({%slug installation/zip%})
+* [Prevent browser caching during version upgrades]({%slug common-kb-browser-cache-buster%})
 * [JavaScript error troubleshooting]({%slug troubleshooting-js-errors%})
 * [NuGet troubleshooting]({%slug troubleshooting-nuget%})
diff --git a/knowledge-base/common-browser-cache-buster.md b/knowledge-base/common-browser-cache-buster.md
@@ -0,0 +1,87 @@
+---
+title: Prevent Browser Caching of Telerik CSS and JavaScript Files
+description: Learn how to implement a cache buster for the Telerik UI for Blazor CSS and JavaScript files. Prevent browser caching for the Telerik static NuGet assets.
+type: how-to
+page_title: How to Prevent Browser Caching and Implement a Cache Buster
+slug: common-kb-browser-cache-buster
+position: 
+tags: telerik, blazor
+ticketid: 
+res_type: kb
+---
+
+## Environment
+
+<table>
+    <tbody>
+        <tr>
+            <td>Product</td>
+            <td>UI for Blazor</td>
+        </tr>
+    </tbody>
+</table>
+
+## Description
+
+This KB article answers the following questions:
+
+* How to prevent browser caching issues with the Telerik CSS theme and JSInterop (JavaScript) file when using static assets from the Telerik NuGet packages?
+* How to implement a version-dependent cache buster for the `all.css` and `telerik-blazor.js` files?
+* How to disable the browser cache for Telerik client assets when upgrading the Telerik UI for Blazor components?
+
+## Solution
+
+To avoid browser caching issues when upgrading the Telerik UI for Blazor version, use the so-called cache busting. Add the components' version number to the Telerik client asset URLs as a query string. In this way, the browser will always load the correct version of the CSS stylesheet and the JSInterop file. Browsers will still use cached Telerik client assets as long as the components version stays the same.
+
+Using the correct client assets [avoids Telerik-related JavaScript errors]({%slug troubleshooting-js-errors%}).
+
+The required approach varies, depending on the Blazor application:
+
+* [Blazor Web Apps and legacy Blazor Server apps](#blazor-web-apps-and-legacy-blazor-server-apps)
+* [Standalone Blazor WebAssembly apps and Hybrid apps](#standalone-blazor-webassembly-apps-and-hybrid-apps)
+
+Normally, there is no need for cache busting when [using the Telerik CDN]({%slug common-features-cdn%}), because the client asset URLs are unique for every Telerik UI for Blazor version.
+
+### Blazor Web Apps and Legacy Blazor Server Apps
+
+You can use reflection to get the Telerik UI for Blazor version at runtime.
+
+1. Pick a type (class) from the Telerik UI for Blazor product. A good candidate is a component that exists in both old and new product versions, such as the [`TelerikRootComponent`]({%slug rootcomponent-overview%}).
+1. Get the component type with `typeof(TelerikRootComponent)`. You may need to use `typeof(Telerik.Blazor.Components.TelerikRootComponent)` if:
+    * The [`Telerik.Blazor.Components` namespace is not registered in `_Imports.razor` as it should]({%slug getting-started/what-you-need%}#namespaces).
+    * The Telerik CSS and JS assets are placed in a `.cshtml` file instead of `App.razor`, for example, in legacy Blazor apps.
+1. Use the [`Assembly.GetName()` method](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assembly.getname?view=net-8.0) and the [`AssemblyName.Version` property](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.assemblyname?view=net-8.0#properties) to extract the Telerik UI for Blazor version.
+
+>caption Adding a cache buster for the Telerik CSS and JavaScript files through reflection
+
+<div class="skip-repl"></div>
+
+````HTML
+@{ var telerikUiForBlazorVersion = typeof(TelerikRootComponent).Assembly.GetName().Version; }
+
+<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css?@telerikUiForBlazorVersion" rel="stylesheet" />
+
+<script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js?@telerikUiForBlazorVersion"></script>
+````
+
+### Standalone Blazor WebAssembly Apps and Hybrid Apps
+
+If the Telerik CSS theme and JavaScript file reside in the `index.html` file, you can hard-code the Telerik UI for Blazor version. In this case, it is crucial to update the query string manually every time when upgrading.
+
+>caption Adding a cache buster for the Telerik CSS and JavaScript files in index.html
+
+<div class="skip-repl"></div>
+
+````HTML
+<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css?{{site.uiForBlazorLatestVersion}}" rel="stylesheet" />
+
+<script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js?{{site.uiForBlazorLatestVersion}}"></script>
+````
+
+## Notes
+
+In addition to cache busting, you can [use a `defer` attribute to load the `telerik-blazor.js` file asynchronously]({%slug getting-started/what-you-need%}#javascript-file) and improve the client-side app performance.
+
+## See Also
+
+* [Adding the Telerik CSS and JavaScript files to a Blazor app]({%slug getting-started/what-you-need%}#css-theme-and-javascript-files)
diff --git a/knowledge-base/common-cannot-read-properties-of-null-reading-addeventlistener.md b/knowledge-base/common-cannot-read-properties-of-null-reading-addeventlistener.md
@@ -59,7 +59,7 @@ The error indicates that the app is still using the old version of our `telerik-
 To resolve the error:
 
 * (if using [CDN]({%slug common-features-cdn%})) Update the `telerik-blazor.js` file URL to the correct version.
-* (if using static assets) Clear the browser cache.
+* (if using static assets) Clear the browser cache and [add a cache buster for the Telerik assets]({%slug common-kb-browser-cache-buster%}).
 * (if using a local JS file) Replace the `telerik-blazor.js` file with the new version.
 
 ## Notes

diff --git a/knowledge-base/common-maximum-call-stack-exceeded.md b/knowledge-base/common-maximum-call-stack-exceeded.md
@@ -45,7 +45,7 @@ The possible causes for the `Maximum call stack size exceeded` error are:
 To resolve the error:
 
 * Use a Telerik UI for Blazor version, which is [compatible with .NET 8]({%slug system-requirements%}#supported-net-versions).
-* Clear the browser cache.
+* Clear the browser cache and [add a cache buster for the Telerik CSS and JavaScript files]({%slug common-kb-browser-cache-buster%}).
 
 Clearing the browser cache will reload the `telerik-blazor.js` file and the error should go away.
 
@@ -56,15 +56,10 @@ If the Telerik UI for Blazor version is up-to-date and the error persists, then
 1. Clear the browser cache.
 1. Reopen Visual Studio and rebuild the app.
 
-
-You can also add a cache buster to the `telerik-blazor.js` script, which will have a similar effect for the end users, as clearing their cache:
-
-`<script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js?version{{site.uiForBlazorLatestVersion}}"></script>`
-
 ## Notes
 
 If you receive a `TelerikBlazor was undefined` JavaScript error after you clear the browser cache, then refer to the [documentation about `TelerikBlazor was undefined`]({%slug troubleshooting-js-errors%}#telerikblazor-was-undefined).
 
 ## See Also
 
-* [JavaScript Errors]({%slug troubleshooting-js-errors%})
+* [Troubleshoot JavaScript Errors]({%slug troubleshooting-js-errors%})
diff --git a/knowledge-base/common-upgrade-breaks-css-theme-styles.md b/knowledge-base/common-upgrade-breaks-css-theme-styles.md
@@ -41,7 +41,7 @@ To resolve the problem, follow the [recommended UI for Blazor upgrade procedure]
 
 * If using the [Telerik **CDN**]({%slug common-features-cdn%}) - update the [stylesheet file URL]({%slug themes-swatches%}) to the correct version.
 * If using a **local** CSS file in `wwwroot` - replace the stylesheet with a compatible one. If the application is using a [**custom theme**, then recreate it]({%slug themes-custom%}#import-custom-theme).
-* If using **static assets** from the NuGet package - clear the browser cache.
+* If using **static assets** from the NuGet package - clear the browser cache and [add a cache buster for the Telerik CSS and JavaScript files]({%slug common-kb-browser-cache-buster%}).
 
 A version update might break custom application CSS styles that are outside the Telerik theme. In this case, then check if the component HTML rendering or CSS classes have changed, and adjust the custom CSS code.
 

diff --git a/knowledge-base/keynotfoundexception-inputelementvalue.md b/knowledge-base/keynotfoundexception-inputelementvalue.md
@@ -46,7 +46,7 @@ This error indicates that the app is using an old or wrong version of the `teler
 To resolve the error:
 
 * (if using [CDN]({%slug common-features-cdn%})) Update the `telerik-blazor.js` file URL to the correct version.
-* (if using static assets) Clear the browser cache.
+* (if using static assets) Clear the browser cache and [add a cache buster for the Telerik CSS and JavaScript files]({%slug common-kb-browser-cache-buster%}).
 * (if using a local JS file) Replace the `telerik-blazor.js` file with the new version.
 
 

diff --git a/troubleshooting/js-errors.md b/troubleshooting/js-errors.md
@@ -75,7 +75,7 @@ Such an error means that the `telerik-blazor.js` script file version does not ma
 
 If you use our CDN to load the script file, make sure the file URL matches the package version. If you load the script as a local file from the `wwwroot` folder, then replace the file. See the [Upgrade Process]({%slug upgrade-tutorial%}#upgrade-process) article for details.
 
-Another common reason is browser caching, if the file comes from the static NuGet assets or a local folder. Clear the browser cache or "hard refresh" the page to fix that. A real server should look at the modified date of those files and serve them fully when they have been upgraded, so in a production environment this should not occur, but a development server is more likely to return a "not modified" response even after the file was updated.
+Another common reason is browser caching, if the file comes from the static NuGet assets or a local folder. Clear the browser cache or "hard refresh" the page to fix that. Consider a [cache buster for the Telerik CSS and JavaScript files]({%slug common-kb-browser-cache-buster%}).
 
 ## Cannot read properties of null (reading 'addEventListener')
 
@@ -115,4 +115,8 @@ Under IE, you may get errors similar to `Object doesn't support property or meth
 
 ## Maximum call stack size exceeded
 
-The error indicates that a [.NET 8 app is using a `telerik-blazor.js` file that is for version `4.5.0` or earlier]({%slug common-kb-maximum-call-stack-exceeded%}). If the Telerik UI for Blazor package version is up-to-date, a possible cause for the error is browser cache.
+The error indicates that a [.NET 8 app is using a `telerik-blazor.js` file that is for version `4.5.0` or earlier]({%slug common-kb-maximum-call-stack-exceeded%}). If the Telerik UI for Blazor package version is up-to-date, a possible cause for the error is browser cache and you may need to [add a cache buster for the Telerik CSS and JavaScript files]({%slug common-kb-browser-cache-buster%}).
+
+## See Also
+
+* [Prevent browser caching during version upgrades]({%slug common-kb-browser-cache-buster%})