Discussion: Guidance on using the new JavaScript Initializers in Blazor/.Net 6

[user72356]

According to https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/?view=aspnetcore-6.0#javascript-initializers, "Use of JS initializers often removes the need to manually add script references when using Razor class libraries (RCLs)."

Right now when I publish a RCL that uses JS interop, I need the user to reference my .js files in his own code, in some manner, as described in https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/?view=aspnetcore-6.0#location-of-javascipt

I fail to grasp how beforeStart(options) and afterStarted(blazor) could be used to load an external .js file. I see that Blazor can be started manually and a script injected according to https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/?view=aspnetcore-6.0#inject-a-script-after-blazor-starts, but that relies on the user changing autostart to false, and I'm not sure where to grab the blazor object from in the beforeStart(options) JS callback. I didn't find documentation of the options and blazor JS objects.

Can anyone shed a little light on that? All I'm trying to do is to automagically load external .js files from an RCL with no user intervention besides loading the RCL NuGet.

[javiercn]

@user72356 thanks for contacting us.

You can name your JS script <>.module.lib.js and it will be automatically imported by Blazor. If you decide to (optionally) export a beforeStart and afterStarted functions from the script, they will be called at the appropriate times.

[javiercn]

@guardrex do we have docs about this?

[guardrex]

@user72356, a "script reference" means that you want to reference the script to run JS that you provide in the RCL and not have the need to have code in the consumer's app reference the script to run the FNs. A JS initializer provides that opportunity (i.e., afterStarted).

If the consumer of your RCL wants to execute JS FNs from script files in the RCL's static assets, then they can access those scripts at ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILENAME (.js)}, per our docs in several spots where we call out that scenario. You/they don't need a JS initializer in this scenario. I think that's what you mean by "load," but you might need to clarify further your scenario if I'm incorrect. Follow the Location of XXX guidance sections for external files where those sections refer to RCL scenarios. Also, see the purple NOTE for JS modules (JavaScript isolation in JavaScript modules section in the Call JS from .NET doc).

We'll take a closer look at that "script reference" line on review of this content. Unless we're going to work on the section now, I'd like to hold off until we reach our post-RC2 docs review.

WRT options and blazor: Indeed, Yes! @javiercn, we do need guidance on those. Nothing was stated in the blog post ...

https://devblogs.microsoft.com/aspnet/asp-net-core-updates-in-net-6-rc-1/#javascript-initializers

If you want to give me something on options and blazor now, I'll roll it into that section now. Otherwise, we'll hit it at docs review time and do it then.

UPDATE: ... and I just noticed this from your new topic on WASM deployment layouts ... beforeStart(wasmOptions, extensions). Actually, we do have a smidgen of content ... just a mention at this point, really ...

In Blazor WebAssembly, beforeStart receives the Blazor WebAssembly options and any extensions added during publishing.

What I'm doing now is adding a cross-link from this content to the upcoming Deployment layout for ASP.NET Core Blazor WebAssembly apps topic as an example of how options and extensions can be used. @user72356, you can see what I'm working from at https://devblogs.microsoft.com/aspnet/custom-deployment-layout-for-blazor-webassembly-apps/. Let me know if you want me to ping u on the docs PR by the end of the week.

[user72356]

Thank you @javiercn and @guardrex for your useful replies.

After reading your messages, I realized that I misunderstood the *.module.lib.js file at first. From reading the docs about the new .Net 6 features in Blazor, in particular https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/?view=aspnetcore-6.0#javascript-initializers, I was under the impression that the new *.module.lib.js file was solely for the purpose of exposing the beforeStart and afterStarted callbacks to the Blazor framework. That impression was reinforced by the sentence "Use of JS initializers often removes the need to manually add script references when using Razor class libraries (RCLs)", which in my head meant that, using initializers, I no longer needed to request consumers of my lib to manually import my lib's *.js files in their code (using for example <script> elements in their index.html, or invoke/import in C#).

I didn't realize (I should have but it was midnight...), that the entire file itself was automatically imported and that one could do other stuff in the file than beforeStart and afterStarted. Indeed I just tried importing my scripts from within the *.module.lib.js file, and that did the trick without needing to involve beforeStart and afterStarted. So I'm guessing these hooks are used for something else which may or may not be of use to me, but the documentation is quite sparse on this at the moment. @guardrex I will take a look at your draft, thanks for looking into this.

I must say that the other Javascript bit needing some documentation attention is the DotNet object. In particular I've been enjoying the ability to write my own JSON revivers but this is entirely undocumented (had to peruse the Typescript source for that one).

[guardrex]

no longer needed to request end-users of my lib to manually reference my lib's *.js files in their code

"script reference" is probably overloaded. I'm in favor of a change, but we'll probably address it later on the 6.0 docs update with engineering support. I might touch it tho on the current PR that I'm working. Either way, we'll see if we can flesh that out further.

... but WRT ...

importing my scripts from within the *.module.lib.js file, and that did the trick

That would also happen for any script in the wwwroot folder when those scripts can be referenced via the conventional path for consuming them. It's fairly well covered in every spot where it's relevant ... I think. I made it a point on a series of UE ("user experience" ... i.e., topic overhauls) to address the referencing of scripts from the app versus a package/RCL via the conventional path.

WRT ...

these hooks are used for something else which may or may not be of use to me, but the documentation is quite sparse on this at the moment

I disagree with that sentiment at the moment (but subject to change my mind any second about it 😄 lol). We'll have to see if we can further clarify, but this section does say ...

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.

... and then ...

... beforeStart is used to customize the loading process, logging level, and other options specific to the hosting model.

... and then ...

... afterStarted is used to initialize libraries by making JS interop calls and registering custom elements.

Nowhere in the docs do we say that {NAME}.module.lib.js is used for you to make scripts available for the app generally for consumer use. What we might end up doing is saying something like, 'For apps to consume scripts, use the approaches outlined in' ... and cross-link to the external JS locations section and to that JS modules bit ... and perhaps the RCL topic that has a bit on consuming static assets from RCLs.

We will be reviewing and updating this content, and I am working on the options, extensions, and blazor params now a bit. We'll have a review before 6.0 GA on this. I'll review your remarks at that time, and we'll continue to 👂 for feedback from other readers on the new content. Thanks for your call outs on this, @user72356. You'll see improvements by 6.0 GA for sure.

[user72356]

Thanks!