Not enough information about how to include custom JS files in WASM library projects

[AderitoSilva]

Description

It is unclear how one should configure a WebAssembly library project that uses JS Interop to include its own JS files for the consuming application.

For example, I want to make a NuGet package that will be consumed by a WebAssembly (non-Blazor) application, and I need to perform some JS interop on my library, which requires some custom JavaScript files. How can I make these JavaScript files available to the consuming application? I've been digging through the docs, but can't find enough info about it.

I suggest a dedicated section or page on the docs about JS Interop for WASM libraries, with a few project configuration examples if possible.

The present way of performing JS Interop in .NET WebAssembly is somewhat tricky as it is, so the docs need to be as clear as possible to compensate the complexity. Although the docs currently have good examples for a WebAssembly application, they still seem to lack important details for library projects.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/client-side/dotnet-interop?view=aspnetcore-9.0&source=recommendations

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/client-side/dotnet-interop.md

Document ID

efff6954-a035-d1da-5975-af04ff7c05ed

Platform Id

ffc7862e-4b77-0c66-5e72-c7ee7e78047b

Article author

@pavelsavara

Metadata

• ID: efff6954-a035-d1da-5975-af04ff7c05ed* PlatformId: ffc7862e-4b77-0c66-5e72-c7ee7e78047b * Service: aspnet-core* Sub-service: client-side

Related Issues

[pavelsavara]

@maraf is there easy way how to include JS file from nuget into wwwroot folder ?

[maraf]

@AderitoSilva The key is razor class library https://learn.microsoft.com/en-us/aspnet/core/blazor/components/class-libraries?view=aspnetcore-9.0&tabs=visual-studio. It can also contain wwwroot folder which is available to the target application.

cc @guardrex

[guardrex]

Covered here ...

• https://learn.microsoft.com/en-us/aspnet/core/blazor/components/class-libraries?view=aspnetcore-9.0&tabs=visual-studio#create-an-rcl-with-static-assets-in-the-wwwroot-folder
• https://learn.microsoft.com/en-us/aspnet/core/blazor/components/class-libraries?view=aspnetcore-9.0&tabs=visual-studio#create-an-rcl-with-javascript-files-collocated-with-components

... and I don't know in this context if all I need to do is add an additional resource cross-link to that article, which I will do. Is there anything else that I would need to call out in the JavaScript [JSImport]/[JSExport] interop article?

[AderitoSilva]

For what I understood, accordingly to the mentioned page, I should create a project using the Razor Class Library template. For what I've learnt by creating a project using that template, the key point for creating a class library with custom static web assets that can be consumed by WebAssembly applications (app projects using the Microsoft.NET.Sdk.WebAssembly SDK) is to use the Microsoft.NET.Sdk.Razor SDK on my class library. My library's "wwwroot" folder content will then be available at the web app's HTTP directory, specifically at "/_content/MyClassLibraryAssemblyName/".

By looking at the source code for the WebAssembly SDK, I learnt that using the Microsoft.NET.Sdk.StaticWebAssets SDK also seems to work. But I guess this SDK is for internal use, and maybe I should avoid using it.

Well, the mentioned docs page indeed covers this subject. I still find it confusing for people wanting to create a class library for a non-Blazor WebAssembly app, though. Maybe you could add a short section on the JS Interop page I linked in the current issue, with a couple of introductory paragraphs related to class libraries, and include a reference to the page you mentioned for more info? I'm suggesting this because the Razor Class Library template seems a bit too deeply tied to Blazor, and it creates several files, including JS Interop ones, that deviate from the [JSImport]/[JSExport] pattern. For WebAssembly application people, it might be enough to know that they only need to target the right SDK in their class libraries' project, but that information currently seems a bit cryptic in the docs.

[guardrex]

the Razor Class Library template seems a bit too deeply tied to Blazor

It's actually for any kind of project. The non-Blazor one is at ...

https://learn.microsoft.com/aspnet/core/razor-pages/ui-class

... which is more page/view focused.

There's a particular section there that pertains to static assets ...

https://learn.microsoft.com/aspnet/core/razor-pages/ui-class#create-an-rcl-with-static-assets

... so perhaps it would be better to cross-link that one.

UPDATE: I placed links to both the Blazor and non-Blazor (Razor Pages) docs. They cover the same concepts, but they have different content. The Blazor article is more tutorial-like with different examples.

I'm suggesting this because the Razor Class Library template seems a bit too deeply tied to Blazor, and it creates several files, including JS Interop ones, that deviate from the [JSImport]/[JSExport] pattern. For WebAssembly application people, it might be enough to know that they only need to target the right SDK in their class libraries' project, but that information currently seems a bit cryptic in the docs.

Perhaps, this article should have a special section of its own on the subject and not rely on cross-linked content. I'll leave that up to the product unit to decide.