Skip to main content
Version: 11.0.x

👉 Web Assembly

Run in the browser with WebAssembly

  1. Install wasm-tools workload tools. See dotnet documentation. If you have an older .NET SDK, it might ask you to install other workloads like wasm-experimental as well.
dotnet workload install wasm-tools
  1. Install or update the dotnet templates to the latest version.
dotnet new install avalonia.templates
  1. Create a new directory for the project.
mkdir BrowserTest
cd BrowserTest
  1. Generate a new project that supports running in the browser. To lookup the available templates via dotnet new list see dotnet documentation.
dotnet new avalonia.xplat
  1. In the console output you will see HTTP and HTTPS links to open the app. In order to run, simply do the following:
cd BrowserTest.Browser
dotnet run

# Output:
# App url: http://localhost:5000/index.html
# App url: https://localhost:5001/index.html

Deployment​

In the BrowserTest.Browser directory, run:

dotnet publish

# ... (build output)
# Generated app bundle at .../bin/Release/net8.0/browser-wasm/AppBundle/

Now you can serve your app from the bin/Release/net8.0/browser-wasm/AppBundle folder (for .NET 8.0, for example) using your favorite web server (such as Azure Static Web Apps).

Beware: Currently using dotnet publish with the -o or --output flag does not produce the AppBundle folder in the output directory. (See this issue.) You'll still have to grab it out of the bin directory at the path specified by the publish output.

Testing AppBundle locally​

You can serve your wasm app from the AppBundle directly using the dotnet-serve tool as follows:

dotnet tool install --global dotnet-serve

dotnet serve -d:bin/Release/net8.0/browser-wasm/AppBundle 

# Output: 
# Starting server, serving bin/Release/net8.0/browser-wasm/AppBundle
# Listening on any IP:
#   http://localhost:49875

Interop​

It is possible to call JavaScript code from the Avalonia Web application. Avalonia app is compatible with standard [JSImport]/[JSExport] interop from Microsoft. You can find more information on their documentation.

Legacy Blazor backend​

Starting from Avalonia 11.0 Avalonia.Browser package relies on build-in .NET interop with better stability and performance. Legacy Blazor backend is still available for compatibility and can be referenced using Avalonia.Browser.Blazor package.

Troubleshooting​

If you have not performed the step to install required workloads, you might encounter errors when running the app in your browser later (e.g. System.DllNotFoundException: libSkiaSharp) and you will need to rebuild again before the app will run.

Keep in mind, that WebAssembly in general as a technology is limited. .NET Multithreading is not supported by any browser and is only available starting .NET 8. Any normal app also has to comply with Browser sandboxing mechanism. And while Avalonia does its best to keep performance high, any WebAssembly GUI apps in some cases might be slow or with older browsers.