How to deploy Blazor Webassembly on GitHub Pages using GitHub Actions

I have been spending quite some time lately playing with Blazor. One of the nice things is that with webassembly you can generate a static website and have it hosted on GitHub Pages for free.
Most importantly, the whole process can be automated with GitHub Actions so you don’t have to worry about it.

It’s not a complicated process, all in all just a few steps. There is only one caveat: if your repository is a “standard” User or Organization repository, you can deploy to Pages only from the master branch.

From the docs:

The default publishing source for user and organization sites is the master branch. If the repository for your user or organization site has a master branch, your site will publish automatically from that branch. You cannot choose a different publishing source for user or organization sites.

Otherwise, if your repository belongs to a Project, you can configure it to deploy from a different branch:

The default publishing source for a project site is the gh-pages branch. If the repository for your project site has a gh-pages branch, your site will publish automatically from that branch.

Project sites can also be published from the master branch or a /docs folder on the master branch.

So what do we have to do in order to see our nice website? The core it’s all here:

name: gh-pages

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/[email protected]
    - name: Setup .NET Core
      uses: actions/[email protected]
      with:
        dotnet-version: 3.1.301
    - name: Publish with dotnet
      run: dotnet publish --configuration Release --output build
    - name: Deploy to Github Pages
      uses: JamesIves/[email protected]/v3
      with:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        BASE_BRANCH: development # The branch the action should deploy from.
        BRANCH: master # The branch the action should deploy to.
        FOLDER: build/wwwroot # The folder the action should deploy.
        SINGLE_COMMIT: true

This GitHub Action workflow is doing all the grunt work for us:

There are also few things to add to the application code as well. First of all, add this javascript snippet to your index.html:

<!-- Start Single Page Apps for GitHub Pages -->
    <script type="text/javascript">
        // Single Page Apps for GitHub Pages
        // https://github.com/rafrex/spa-github-pages
        // Copyright (c) 2016 Rafael Pedicini, licensed under the MIT License
        // ----------------------------------------------------------------------
        // This script checks to see if a redirect is present in the query string
        // and converts it back into the correct url and adds it to the
        // browser's history using window.history.replaceState(...),
        // which won't cause the browser to attempt to load the new url.
        // When the single page app is loaded further down in this file,
        // the correct url will be waiting in the browser's history for
        // the single page app to route accordingly.
        (function (l) {
            if (l.search) {
                var q = {};
                l.search.slice(1).split('&').forEach(function (v) {
                    var a = v.split('=');
                    q[a[0]] = a.slice(1).join('=').replace(/~and~/g, '&');
                });
                if (q.p !== undefined) {
                    window.history.replaceState(null, null,
                        l.pathname.slice(0, -1) + (q.p || '') +
                        (q.q ? ('?' + q.q) : '') +
                        l.hash
                    );
                }
            }
        }(window.location))
    </script>
    <!-- End Single Page Apps for GitHub Pages -->

As you can see from the comment, this code helps to handle URLs and redirections.

You’ll also have to update the <base> tag with the repository name:

<base href="/BlazorOnGitHubPages/" />

So if the name is BlazorOnGitHubPages, the final URL will be something like https://mizrael.github.io/BlazorOnGitHubPages/ (which happens to be the one I’m using, feel free to try it).

The next step is to add a 404.html page and an empty .nojekyll file in the /wwwroot folder. GitHub Pages are built using Jekyll and it does not build anything that starts with _ . Blazor, however, generates a _framework subfolder inside /wwwroot and as you can imagine, it’s quite important.

How to deploy Blazor Webassembly on GitHub Pages using GitHub Actions
Scroll to top