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.


7 Comments

Mike · December 30, 2019 at 18:21

Can you host multiple blazor apps in one storage account? Meaning root/app1 and root/app2?

    Mika Berglund · December 30, 2019 at 20:49

    Do you mean an Azure storage account? Yes, you can. You just follow the same principles as you would when prepping the app to run in a GitHub Pages project site, like the sample app for this article. You find that at https://mikaberglund.github.io/hosting-blazor-apps-on-github-pages/

    Similarly, you can enable the static website feature on an Azure storage account, which will give you a $web blob container in that storage account, which represents the root of the static website for your storage account. In that container, you can create whatever folder structure you like. Just remember to make sure your application is set up to run in the folder you specify.

      roustan thierry · April 23, 2020 at 09:25

      404.html is a good idea. But is incompatible with pwa app who need http 200 for offline page no?

        Mika Berglund · April 25, 2020 at 08:14

        I’m not quite sure what it does to PWAs. But you definitely need 404.html to make routing work without server logic.

ปั้มไลค์ · June 23, 2020 at 14:26

Like!! I blog frequently and I really thank you for your content. The article has truly peaked my interest.

fortnite v bucks generator · July 26, 2020 at 16:30

You are so interesting! I do not think I have read something
like this before. So good to find someone with a few genuine thoughts on this
subject matter. Really.. thanks for starting this up.
This site is one thing that is required on the internet, someone with a bit of originality!

    Mika Berglund · July 27, 2020 at 00:01

    Thanks

Leave a Reply

Your email address will not be published. Required fields are marked *