Cover image for Hosting Blazor WebAssembly app on GitHub Pages

Hosting Blazor WebAssembly app on GitHub Pages

cirio profile image Andrea Cirioni ・4 min read

Credit cover image: Unsplash

πŸ”₯ Blazor WebAssembly is a new framework that promises rich interactive UIs using C# instead of JavaScript. πŸ”₯

At current, the framework is in preview for ASP.NET Core 3.1. When I read about it, I've decided to try a deploy of a basic project on Github Pages.

Table Of Contents

Initial Setup: πŸ”¨

First of all, you must install the template. Run the following command in a command shell:

dotnet new -i Microsoft.AspNetCore.Blazor.Templates::3.1.0-preview4.19579.2

After that, we can use blazorwasm command to create our first Blazor WebAssembly App.

dotnet new blazorwasm 

The project structure will be like this:

Alt Text

Finally, we can publish the project

dotnet publish -c Release

and view the output command on the path ~\publish\yourProject\dist_

Deploy on GitHub Pages: πŸ“„

1. Replace Index.html page

<!DOCTYPE html>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Blazor Pages</title>
    <base href="/" />
    <link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
    <link href="css/site.css" rel="stylesheet" />

    <!-- 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) : '') +
    <!-- End Single Page Apps for GitHub Pages -->

    <div id="blazor-error-ui">
        An unhandled error has occurred.
        <a href="" class="reload">Reload</a>
        <a class="dismiss">πŸ—™</a>
    <script src="_framework/blazor.webassembly.js"></script>

2. Add Jekyll file

GitHub Pages uses Jekyll to build Pages sites. Because of the way that Jekyll works, any files or folders that start with _, ., # or end with ~ are not built.

The result is that folders as _framework_ , mandatory for a Blazor WebAssembly running project they aren't processed.

To solve it, you must create a .nojekyll file under root of published. This is quite important .

3. Add 404.html Error Page

<!DOCTYPE html>
    <meta charset="utf-8">
    <title>Single Page Apps for GitHub Pages</title>
    <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 takes the current url and converts the path and query
      // string into just a query string, and then redirects the browser
      // to the new url with only a query string and hash fragment,
      // e.g. http://www.foo.tld/one/two?a=b&c=d#qwe, becomes
      // http://www.foo.tld/?p=/one/two&q=a=b~and~c=d#qwe
      // Note: this 404.html file must be at least 512 bytes for it to work
      // with Internet Explorer (it is currently > 512 bytes)
      // If you're creating a Project Pages site and NOT using a custom domain,
      // then set segmentCount to 1 (enterprise users may need to set it to > 1).
      // This way the code will only replace the route part of the path, and not
      // the real directory in which the app resides, for example:
      // https://username.github.io/repo-name/one/two?a=b&c=d#qwe becomes
      // https://username.github.io/repo-name/?p=/one/two&q=a=b~and~c=d#qwe
      // Otherwise, leave segmentCount as 0.
      var segmentCount = 0;
      var l = window.location;
        l.protocol + '//' + l.hostname + (l.port ? ':' + l.port : '') +
        l.pathname.split('/').slice(0, 1 + segmentCount).join('/') + '/?p=/' +
        l.pathname.slice(1).split('/').slice(segmentCount).join('/').replace(/&/g, '~and~') +
        (l.search ? '&q=' + l.search.slice(1).replace(/&/g, '~and~') : '') +

3. Update base path on Index.html Page

The <base> url in index.html will need to be modified depending on where the project is deployed. If you have a repository with a structure like this:


you need to edit base tag as

  <base href="/MyFirstBlazorApp/" />

If deploying on the root level, set segmentCount = 0 in 404.html as well.

-- πŸŽ‰ Enjoy with Blazor πŸŽ‰ --

Posted on Jan 11 by:

cirio profile

Andrea Cirioni


I'm a web developer who loves his work.


markdown guide

I used a powershell script to deploy to github pages through the docs folder options. It's rudimentary and can probably be improved upon but it works
with that file at the root of your solution. change some aspects of the variables and select the option to add github pages docs folder and you should be good.


The link is broken, please can you reupload the script? Thank you.


well done, thank you for sharing. It's would be interesting to manage dynamically the 'base href' tag.


i have a problem...

Failed to find a valid digest in the 'integrity' attribute for resource 'tetradogpwa.github.io/GeneradorCon...' with computed SHA-256 integrity '80L/hSwps3gjABzV78X6mehoDDgsLkm1pKpSS6fAqiE='. The resource has been blocked.

can somebody help me?


Thanks for the guide, Andrea.

I want to deploy the site to a different branch instead of master, and it seems like adding the .nojekyll file causes my branch to not be eligible under the GitHub Pages settings (the branch doesn't show up).

Any ideas why this could be happening?


Hi Mauro,
Your repository is public? Have you tried to follow this issues link?