Blazor JS initializers

aspnetcore/blazor/fundamentals/startup.md

@@ -18,6 +18,10 @@ Configure a manual start in the `wwwroot/index.html` file (Blazor WebAssembly) o
 * Add an `autostart="false"` attribute and value to the `<script>` tag for the Blazor script.
 * Place a script that calls `Blazor.start` after the Blazor `<script>` tag and inside the closing `</body>` tag.
 
+## JavaScript initializers
+
+[!INCLUDE[](~/blazor/includes/js-initializers.md)]
+
 ## Initialize Blazor when the document is ready
 
 The following example starts Blazor when the document is ready:

aspnetcore/blazor/includes/js-initializers.md

@@ -0,0 +1,38 @@
+---
+no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
+---
+JavaScript (JS) initializers execute logic before and after a Blazor app loads. JS initializers are useful in the following scenarios:
+
+* Customizing how a Blazor app loads.
+* Initializing libraries before Blazor starts up.
+* Configuring Blazor settings.
+
+JS initializers are detected as part of the build process and imported automatically in Blazor apps. Use of JS initializers often removes the need to manually add script references when using Razor class libraries (RCLs).
+
+To define a JS initializer, add a JS module to the project named `{NAME}.lib.module.js`, where the `{NAME}` placeholder is the assembly name, library name, or package identifier. Place the file in the project's web root, which is typically the `wwwroot` folder.
+
+The module exports either or both of the following conventional functions:
+
+* `beforeStart`: Called before Blazor starts. For example, `beforeStart` is used to customize the loading process, logging level, and other options specific to the hosting model.
+  * In Blazor WebAssembly, `beforeStart` receives the Blazor WebAssembly options and any extensions added during publishing.
+  * In Blazor Server, `beforeStart` receives the circuit start options.
+  * In [`BlazorWebViews`](/mobile-blazor-bindings/walkthroughs/hybrid-hello-world#mainrazor-native-ui-page), no options are passed.
+* `afterStarted`: Called after Blazor is ready to receive calls from JS. For example, `afterStarted` is used to initialize libraries by making JS interop calls and registering custom elements. The Blazor instance is passed to `afterStarted` as an argument.
+
+The following example demonstrates JS initializers for `beforeStart` and `afterStarted`. For the filename of the following example:
+
+* Use the app's assembly name in the filename if the JS initializers are consumed as a static asset in the project. For example, name the file `BlazorSample.lib.module.js` for a project with an assembly name of `BlazorSample`. Place the file in the app's `wwwroot` folder.
+* Use the project's library name or package identifier if the JS initializers are consumed from an RCL. For example, name the file `RazorClassLibrary1.lib.module.js` for an RCL with a package identifier of `RazorClassLibrary1`. Place the file in the library's `wwwroot` folder.
+
+```javascript
+export function beforeStart(options) {
+    console.log("beforeStart");
+}
+
+export function afterStarted(blazor) {
+    console.log("afterStarted");
+}
+```
+
+> [!NOTE]
+> MVC and Razor Pages apps don't automatically load JS initializers. However, developer code can include a script to fetch the app's manifest and trigger the load of the JS initializers.

aspnetcore/blazor/javascript-interoperability/index.md

@@ -34,6 +34,10 @@ For more information, see <xref:blazor/js-interop/call-javascript-from-dotnet#ca
 
 JS interop calls are asynchronous by default, regardless of whether the called code is synchronous or asynchronous. Calls are asynchronous by default to ensure that components are compatible across both Blazor hosting models, Blazor Server and Blazor WebAssembly. On Blazor Server, JS interop calls must be asynchronous because they're sent over a network connection. For apps that exclusively adopt the Blazor WebAssembly hosting model, synchronous JS interop calls are supported. For more information, see <xref:blazor/performance?pivots=webassembly#consider-the-use-of-synchronous-calls>.
 
+## JavaScript initializers
+
+[!INCLUDE[](~/blazor/includes/js-initializers.md)]
+
 ## Location of JavaScipt
 
 Load JavaScript (JS) code using any of the following approaches:

aspnetcore/blazor/performance.md

@@ -539,11 +539,11 @@ In addition to implementing the <xref:Microsoft.AspNetCore.Components.IHandleEve
 
 Blazor's recreation of [lambda expression delegates](xref:blazor/components/event-handling#lambda-expressions) for elements or components in a loop can lead to poor performance.
 
-The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its [`@onclick`](xref:mvc/views/razor#onclick) event, which is fine if there aren't many buttons to render:
+The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its `@onclick` event, which is fine if there aren't many buttons to render:
 
 [!code-razor[](~/blazor/samples/6.0/BlazorSample_WebAssembly/Pages/event-handling/EventHandlerExample5.razor)]
 
-If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's [`@onclick`](xref:mvc/views/razor#onclick) delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
+If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's `@onclick` delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
 
 `Pages/LambdaEventPerformance.razor`:
 
@@ -1268,11 +1268,11 @@ In addition to implementing the <xref:Microsoft.AspNetCore.Components.IHandleEve
 
 Blazor's recreation of [lambda expression delegates](xref:blazor/components/event-handling#lambda-expressions) for elements or components in a loop can lead to poor performance.
 
-The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its [`@onclick`](xref:mvc/views/razor#onclick) event, which is fine if there aren't many buttons to render:
+The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its `@onclick` event, which is fine if there aren't many buttons to render:
 
 [!code-razor[](~/blazor/samples/5.0/BlazorSample_WebAssembly/Pages/event-handling/EventHandlerExample5.razor)]
 
-If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's [`@onclick`](xref:mvc/views/razor#onclick) delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
+If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's `@onclick` delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
 
 `Pages/LambdaEventPerformance.razor`:
 
@@ -1989,11 +1989,11 @@ In addition to implementing the <xref:Microsoft.AspNetCore.Components.IHandleEve
 
 Blazor's recreation of [lambda expression delegates](xref:blazor/components/event-handling#lambda-expressions) for elements or components in a loop can lead to poor performance.
 
-The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its [`@onclick`](xref:mvc/views/razor#onclick) event, which is fine if there aren't many buttons to render:
+The following component shown in the [event handling article](xref:blazor/components/event-handling#lambda-expressions) renders a set of buttons. Each button assigns a delegate to its `@onclick` event, which is fine if there aren't many buttons to render:
 
 [!code-razor[](~/blazor/samples/3.1/BlazorSample_WebAssembly/Pages/event-handling/EventHandlerExample5.razor)]
 
-If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's [`@onclick`](xref:mvc/views/razor#onclick) delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
+If a large number of buttons are rendered using the preceding approach, rendering speed is adversely impacted leading to a poor user experience. To render a large number of buttons with a callback for click events, the following example uses a collection of button objects that assign each button's `@onclick` delegate to an <xref:System.Action>. The following approach doesn't require Blazor to rebuild all of the button delegates each time the buttons are rendered:
 
 `Pages/LambdaEventPerformance.razor`: