Hosting Blazor Applications on GitHub Pages

Published by Mika Berglund on December 29, 2019December 29, 2019

Last night I was writing my previous article about anchor links in Blazor applications. I got a few comments on it that triggered my interest to dig a bit deeper into the subject. Thanks Chris 😉

Previously, I had only been running Blazor applications on the root of a site. This made me completely miss the point of the <base href="/" /> element, which is added by default to Blazor applications. That element isn’t required until you run your application in a subdirectory of your site.

That is why I started to look into GitHub Pages. GitHub Pages allows you to host static content on GitHub. You can publish any GitHub repository to a project site in GitHub Pages. A project site will be published to a subdirectory under your account. An example of that is the sample application I wrote for this article, which you can find running at mikaberglund.github.io/hosting-blazor-apps-on-github-pages. The application is published in the /docs folder in the master branch of the repository.

Considerations for GitHub Pages

Blazor is a SPA Framework, which typically only has one physical page that acts as the starting point for the application. The application provides a routing mechanism that loads the view associated with the current route (the path in the browser’s address bar).

This is all good as long as the Blazor application with its routing engine is loaded. But what if you reload the browser window? Or if you copy the address in your browser, and send it off to a friend? Then the request will go all the way to the server. Since there is no corresponding folder or file that would match the request, the server returns a 404 Not Found error message.

ASP.NET Core handles this by loading the application’s startup page, if no better matching resource or route is available.

But since GitHub Pages only hosts static content, no server-side processing is possible. One solution to this is to leverage custom 404 (not found) pages in GitHub Pages. The basic idea in this solution is that the custom 404 page will store the current route (URL) in the browser’s history, and redirect the browser to index.html (the application’s startup page) with the original route as parameters. index.html will then rewrite the URL so that Blazor’s routing engine will understand it. Read more about this solution on the Microsoft Docs site.

If you publish your application on a project site, you need to modify the <base /> element in your index.html file. My sample app associated with this article runs in the /hosting-blazor-apps-on-github-pages folder. This means that I need to change the element as shown below.

<base href="/hosting-blazor-apps-on-github-pages/" />

A Simplified Solution

The solution described above is pretty cool. You can probably apply that to any kind of SPA Framework hosted on any kind of service that supports static content with customizable 404 pages.

However, this got me thinking whether the solution could be simplified. If the custom 404 page “catches” any incoming request that does not have a corresponding physical file, why could that 404 page not be the application’s startup page too? Why would you need to modify the incoming request and redirect to index.html when you could serve the application directly from 404.html?

So I published the sample application to the /docs folder, renamed index.html to 404.html, and pushed my changes to the remote repository. As you can see in the /docs folder, there is no index.html, only 404.html. Still, the application works just fine.

There is one downside to this though. When you load your application, GitHub Pages will return the HTTP status 404 (not found), even if your application loads completely fine. So, if this becomes an issue for you, then you need to do it the way it is described on the Microsoft Docs site.

Final Thoughts

Running the application directly from the 404.html page instead of doing some tweaking and redirecting to the index.html is obviously a more simple solution. However, so far I have only tested it with the sample Blazor application I wrote for this article. That sample application is pretty simple, so I’m going to add more advanced routing scenarios to it later on to be more certain. And, as I said, you will get a 404 response status to every request to your application.

I already published the Blazor Bootstrap Showroom application on GitHub Pages. You can find it here. I wrote about the Blazor Bootstrap component library a while ago here on my blog. If you want to learn more about this project and how you can use it in your Blazor application, have a look at the Blazor Bootstrap Wiki.

If you manage to publish your SPA application directly from the custom 404 page on GitHub Pages, I’d be happy to hear about it. Feel free to leave a comment below and let me know.