Handling Custom 404 Page on GH Pages with Blazor WASM

This post is over a year old, some of this information may be out of date.

It might be necessary to implement the custom 404 page while developing a Blazor WebAssembly (WASM) app. But when you deploy your Blazor WASM app to GitHub Pages, it only shows GitHub's 404 page, not yours. Although there are many workarounds for this, throughout this post, I'm going to discuss how to use a Blazor web component for the 404 page on GitHub Pages.

You can download the sample application on this GitHub repository.

Blazor WASM – Default 404 Page

The default 404 page right after you create a Blazor WASM app project looks like this:

Default 404 page

It's because App.razor defines like that.

@* BlazorApp1.App.razor *@

<Router AppAssembly="@typeof(App).Assembly">
    ...
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <LayoutView Layout="@typeof(MainLayout)">
            @* ⬇️⬇️⬇️ This is the content ⬇️⬇️⬇️*@
            <p role="alert">Sorry, there's nothing at this address.</p>
            @* ⬆️⬆️⬆️ This is the content ⬆️⬆️⬆️*@
        </LayoutView>
    </NotFound>
</Router>

Therefore, all you need to customise your 404 page is this part.

Blazor WASM – Custom 404 Page

The sample app used in this post uses a customised 404 page. For the custom 404 page, create a web component called NotFound.razor.

@* Fitability.Home.Components.NotFound.razor *@

<div class="row">
    <div class="col-6">
        <img src="images/banner-3840x1920.png" class="img-fluid" alt="banner" />
    </div>
    <div class="col-6 d-flex align-items-center">
        <div class="row">
            <div class="col-12">
                <h1 class="text-center">Not Found!</h1>
                <p class="text-center fs-2">Your requested page doesn't exist.</p>
                <p class="text-center fs-3"><a href="/" class="btn btn-primary btn-lg">Home</a></p>
            </div>
        </div>
    </div>
</div>

Then, import it within the LayoutView component of App.razor

@* Fitability.Home.App.razor *@

<Router AppAssembly="@typeof(App).Assembly">
    ...
    <NotFound>
        <LayoutView Layout="@typeof(MainLayout)">
            @* ⬇️⬇️⬇️ Add the NotFound component here ⬇️⬇️⬇️*@
            <NotFound />
            @* ⬆️⬆️⬆️ Add the NotFound component here ⬆️⬆️⬆️*@
        </LayoutView>
    </NotFound>
</Router>

Run your Blazor WASM app on your local machine, and you will see the custom 404 page.

Custom 404 page

GitHub Pages – Default 404 Page

However, deploy your Blazor WASM app to GitHub Pages and visit any non-existing URL. Then you will see GitHub's default 404 page.

GitHub default 404 page

It's because GitHub displays their default 404 page if someone visits the non-existing page. Let's change this.

GitHub Pgaes – Custom 404 Page

The 404.html file MUST physically exist to use the custom 404 page on your GitHub Pages. Generally speaking, you can prepare hard-coded 404.html for this purpose. But we're using the Blazor WASM's routing pipeline.

Copy the existing index.html file to 404.html. Both are fundamentally the same file as each other.
Create the 404.razor page and import the NotFound component. The routing path of this 404.razor page MUST be /404.html.
```
@* Fitability.Home.Pages.404.razor *@

@page "/404.html"

<NotFound />
```

Deploy your Blazor WASM app to GitHub Pages again and visit any non-existing URL. Then, you will be able to see your custom 404 page.

Custom 404 page on GH Pages

It's because GitHub Pages looks for the physical 404.html file. This file runs on the Blazor WASM routing pipeline. Therefore, you can write any business logic on your 404 page.

So far, we've walked through how to deal with the custom 404 page of the Blazor WASM app running on GitHub Pages.

Want to know more about Blazor?

It's great if you visit those sites for more Blazor stuff.