Deploying an ASP.NET Blazor WebAssembly App to GitHub Pages

ASP.NET Blazor is a new web framework from Microsoft that allows you to build interactive web user interfaces using C# and HTML. Blazor apps can be hosted in different ways, including running client-side in the browser using WebAssembly. In this post, I’ll walk through how to deploy a Blazor WebAssembly app to GitHub Pages to host it for free!

Creating a New Blazor WebAssembly App

First, we need a Blazor WebAssembly app to deploy. I’ll use the .NET CLI to generate a new Blazor WebAssembly project:

dotnet new blazorwasm -o BlazorApp
cd BlazorApp
dotnet run

It will create a new Blazor WebAssembly project in a folder called BlazorApp and run it. Navigating to http://localhost:5000 in the browser should show the default Blazor template page.

Configuring the App for GitHub Pages

To deploy to GitHub Pages, we need to make a few tweaks to our Blazor WebAssembly app:

1. Set the <base> tag in index.html to use the GitHub Pages URL. This allows the app to properly load CSS, JS, and other assets when deployed.
2. Have the build output publish to the /docs folder. GitHub Pages will host from this folder.
3. Generate static HTML from the Razor components for hosting statically on GitHub Pages.

Let’s go through each of these steps:

Setting the Base Tag

In the wwwroot/index.html file, change the <base> tag to this:

<base href="https://<username>.github.io/<repo>/" />

Replace <username> with your GitHub username and <repo> with the name of the GitHub repository you'll use. This makes all relative links work properly when deployed to that GitHub Pages URL.

Configuring Publish Output

Next, we need to configure the app to publish the build output to the /docs folder. In the Blazor WebAssembly project file (BlazorApp.csproj) add:

<PropertyGroup>
  <PublishRepositoryUrl>true</PublishRepositoryUrl>
  <PublishUrl>docs</PublishUrl>
</PropertyGroup>

It makes dotnet publish put the build output in /docs.

Generating Static HTML

Finally, we need to generate static HTML files from the Razor components so the Blazor app can be hosted as static files. This is done with the Blazor Static Web Apps NuGet package.

Install it:

dotnet add package Microsoft.AspNetCore.Components.WebAssembly.Build --version 6.0.7

And call its static generation tool in the project file:

<Target Name="StaticWebAssets" AfterTargets="Publish">
  <Exec Command="dotnet msbuild /t:GenerateStaticWebAssets /p:Configuration=$(Configuration)" />  
</Target>

This will generate a wwwroot/_content folder with static HTML files when we publish.

Publishing and Pushing to GitHub

With those steps complete, we’re ready to publish and push to GitHub!

First, publish the app locally:

dotnet publish -c Release

This will generate the /docs folder with static HTML and other assets.

Next, commit the changes and push the project to a new GitHub repository:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<user>/<repo>.git
git push -u origin main

Replace <user> and <repo> with your info.

GitHub will automatically host the docs folder on your GitHub Pages URL! It may take a few minutes to go live.

You can now visit https://<user>.github.io/<repo> to see your deployed Blazor WebAssembly app!

Custom Domains, CI/CD, and More

This covers the basics of deploying a Blazor WebAssembly site to GitHub Pages. Some other ideas for taking it further:

• Set up a custom domain like www.myapp.com to point to your GitHub Pages site.
• Configure continuous integration (CI) like GitHub Actions to build and deploy on each commit.
• Add more advanced GitHub Pages configuration like themes.
• Use a third-party static site/Jamstack host like Netlify instead of GitHub Pages.

Blazor WebAssembly opens up lots of possibilities for static and client-side web development with .NET! I hope this gives you a good starting point for deploying your Blazor apps. Let me know in the comments if you have any other questions!