Hosting Blazor WebAssembly app on GitHub Pages

Andrea Cirioni — Sat, 11 Jan 2020 10:17:06 +0000

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.

cirio / blazor-githubpages-example

Setup
Edit Index.html
Add Jekyll file
Add 404 Page
Update Base Path

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:

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>
<html>
<head>
    <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" />
</head>
<body>
    <app>Loading...</app>

    <!-- 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 -->

    <div id="blazor-error-ui">
        An unhandled error has occurred.
        <a href="" class="reload">Reload</a>
        <a class="dismiss">🗙</a>
    </div>
    <script src="_framework/blazor.webassembly.js"></script>
</body>
</html>

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>
<html>
  <head>
    <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.replace(
        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~') : '') +
        l.hash
      );
    </script>
  </head>
  <body>
  </body>
</html>

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:

MyFirstBlazorApp
|
|
└───index.html
└───sample-data
└───404.html
└───_framework
...
...

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 🎉 --

DEV Community: Andrea Cirioni