The easier way to publish your Blazor WebAssembly app for GitHub Pages

Publishing your Blazor Wasm app to GitHub Pages isn't difficult, but is chores.

As you know, your Blazor WebAssembly app can be deployed to GitHub Pages.

The good articles about how to deploy a Blazor WebAssembly app to GitHub Pages are already exists, like the below.

• "How to deploy ASP.NET Blazor WebAssembly to GitHub Pages"

The following list is the main task to deploy a Blazor WebAssembly app to GitHub Pages.

• Add a .nojekyll file to avoid the "Jekyll" translation.
• Add a .gitattribute file to avoid changing end-of-line characters.
• Rewrite the base URL inside the index.html.
• Copy the index.html to the 404.html.

Each task in the list above is not difficult, but rather a simple operation.

Implementation of these 4 tasks to GitHub workflow .yml file every time is very boring to me, so I thought it must be automated.

"Publish SPA for GitHub Pages" NuGet Package

Finally, I made a new NuGet package that makes a Blazor Wasm app project to be available to publishing to GitHub Pages including 4 tasks described in the before section.

That NuGet package is "Publish SPA for GitHub Pages".

• NuGet Gallery | PublishSPAforGitHubPages.Build

With this NuGet package, what you should do to publishing your Blazor Wasm app is just ONLY 2 STEPS as following.

1. Add the "PublishSPAforGitHubPages.Build" NuGet package to the Blazor Wasm app project.

$ dotnet add package PublishSPAforGitHubPages.Build

1. Specify the GHPages=true MSBuild property when you publish the Blazor Wasm project.

$ dotnet publish -c:Release -p:GHPages=true

After doing these 2 steps, the published contents are made to be suitable for GitHub Pages deploying.

It is easy, isn't it? :)

Due to "PublishSPAforGitHubPages.Build" NuGet package taking care of chore tasks that makes the app to be suitable for GitHub Pages, the GitHub Workflow .yml code that to deployment the app can be simplified.

For example, .github/workflows/*.yml file that deploys the Blazor Wasm app to GitHub Pages will be like as below.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Checkout the code
      - uses: actions/checkout@v2

      # Install .NET Core SDK
      - name: Setup .NET Core
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      # Publish the site
      - name: Publish
        #      Don't missing to add "p:GHPages=true". 👇
        run: dotnet publish ProjectDir/Project.csproj -p:GHPages=true -o:public -c:Release

      # Deploy the site
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: public/wwwroot
          force_orphan: true

Offline supported PWA

When you make your Blazor WebAssembly on GitHub Pages be PWA offline supported, only changing the index.html (ex. modifying the base URL inside it) and nothing to do after that causes Blazor PWA could not work.

A usual Blazor PWA project calculates the hash for each content file and stores them into the service-worker-assets.js file during publishing time. And a web browser does the integrity checking with the service-worker-assets.js file when loading that Blazor PWA.

// 📜 service-worker-assets.js
self.assetsManifest = {
  "assets": [
    {
      "hash": "sha256-lqehqsKUaAnnNozj4bnXdM6UlKdzXsxJnVsMN+SjhAY=",
      "url": "index.html"
    },
    ...

Therefore, if you only change the index.html, but nothing cares for the service-worker-assets.js, the integrity checking will fail, and your Blazor PWA will not work.

Fortunately, the "PublishSPAforGitHubPages.Build" package (since ver.1.3.5, Dec. 2021) updates hash values appropriately inside the service-worker-assets.js file automatically during publishing time. So you don't have to worry about the integrity checking on Blazor PWA you want to publish on GitHub Pages if you use the latest version of the "PublishSPAforGitHubPages.Build" package to deploy your Blazor PWA on GitHub Pages. The "PublishSPAforGitHubPages.Build" will take care of all those concerns.

And also, "Brotli" compression is enabled!

And one more thing, the published contents with the "PublishSPAforGitHubPages.Build" NuGet package is already enabled "Brotli" compression loading, out of the box!

"PublishSPAforGitHubPages.Build" injects the custom loader script into the index.html automatically for loading "Brotli" compressed contents.

In my case, the size of my Blazor Wasm app contents was reduced from 17.3 MBytes to 7.7 MBytes by "Brotli" compression.

It is a 45% compression rate.

For more detail about "Brotli compression in Blazor Wasm apps" please see also the official documentation site.

• "Host and deploy ASP.NET Core Blazor WebAssembly | Microsoft Docs"

Conclusion

Adding the "PublishSPAforGitHubPages.Build" package to your Blazor WebAssembly project makes what you should do to publish it on GitHub Pages is only specifying the GHPages=true MSBuild property. There is no problem even if your Blazor WebAssembly is offline-supported PWA.

And the "PublishSPAforGitHubPages.Build" package makes the published contents to be able to load "Brotli" compressed contents.

I'm happy if somebody could save their time by using "PublishSPAforGitHubPages.Build" NuGet package.

Happy coding! :)

Comments

[NAKGIOE.ORG]

dotnet publish -c:Release -p:GHPages=true
I receive the following error message:
c:...\6.0.1\Sdk\wasmapp.native.targets(425,5) error MSB3073: The command "emcc --version" exited with code -1073741515

The error occurs only when «-c:Release» option is enabled to .NET Intermediate Language (IL) linking also run to reduce the size of the published app.

From other messages it looks like it's emsdk installs unsupported Python version for Windows 7
My system:
Windows 7 64bit (SP1)
.NET 6.0.101
standard blazorwasm app, created by running in the command line:
dotnet new blazorwasm -o nakigoe.org

I am trying to create a website on razor components out my AMP-HTML & CSS website with tons of CSS animations and graphics — a perfect task for WebAssembly. And to upgrade my site navigation.

I receive the following error message when running build on GitHub pages:
Run sed -i 's///g' release/wwwroot/index.html
sed: can't read release/wwwroot/index.html: No such file or directory

What has gone wrong with the project and the .yml file?

So it was faster to host on another provider
You can take a look at my live Blazor WebAssembly app here:

NAKIGOE.ORG

[Mariusz]

I think I'll try this out soon :-)

[Sanjib]

Thanks for informative article. It help me a lots.