Deploy Blazor WASM to GitHub Pages using GitHub Actions

Blazor WebAssembly was out a couple of weeks ago, and I can’t stop playing with it! It’s such a refreshing pause from all the JavaScript SPA frameworks.

As with any other SPA framework, you can deploy Blazor WASM in Github Pages! Today I’ll be showing you step by step how to do so. We will be using GitHub Actions to automate the deployment process.

Project preparations


Let’s begin with the most important file that lets a SPA work on GitHub Pages, the 404.html file.
As you know, SPAs only have one entry file, which is the index.html file. The JavaScript is the one handling routing. Because of this, links to specific pages (e.g. won’t work, because there is no page1.html nor page1/index.html.

GitHub Pages will try and return a 404 status code with an error page. The good thing is that it can be customized! Let’s go ahead and add a custom 404.html in our wwwroot folder (taken from spa-github-pages).

There are two important things to note here, which are explained very well by the description:

  • An url like becomes will become Notice that the path /one/two becomes a parameter, so this essentially redirects to the index.html with extra parameters.
  • Pay attention to the comment about segmentCount, you might need to change it to 1.
Don't forget to change the title in the file!


As we saw in the previous section, the 404.html file adds a p parameter that contains the page the user asked for. We would need to use that in our index.html file. Let’s modify our wwwroot/index.html file to add this script:

Disabling Jekyll

GitHub Pages uses Jekyll, and by default, directories that start with an underscore are treated specially. This means that our two important folders, _content and _framework won’t get served.

To fix this, we only need to create the empty file wwwroot/.nojekyll.

GitHub Actions

Now for the deployment part!


To keep the repository clean, we will be deploying the website in a separate branch gh-pages. Let’s create an empty one now:

Next, configure GitHub Pages to use this branch in the repository:

GitHub Pages repository settings

GitHub Pages repository settings


Let’s go over this step by step:

  1. Publish app: We publish the project using dotnet publish . If your project is in a subfolder, add cd Path/To/Project && in the start.
  2. Rewrite base href: In the index.html file, there is <base href="/" />. We need to change the / into our GitHub Repository name in order for the navigation to work.
  3. GitHub Pages: Lastly, we push our published website into the gh-pages branch.
If you're using a custom domain (e.g., without subfolders), then you should delete the Rewrite base href step!

If you configured everything right, running this should deploy the project successfully!



As you can see, it’s fairly easy to deploy a Blazor Wasm project in GitHub Pages. You can, if you want to, skip the GitHub Actions step and publish the project locally, then uploading it whenever needed. But you might as well use the free GitHub Actions minutes!

Hope you liked the post, see you next time.

Zanid Haytam Written by:

Zanid Haytam is an enthusiastic programmer that enjoys coding, reading code, hunting bugs and writing blog posts.

comments powered by Disqus