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.
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 the404.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".
With this NuGet package, what you should do to publishing your Blazor Wasm app is just ONLY 2 STEPS as following.
- Add the "PublishSPAforGitHubPages.Build" NuGet package to the Blazor Wasm app project.
$ dotnet add package PublishSPAforGitHubPages.Build
- 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.
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! :)
Top comments (3)
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
I think I'll try this out soon :-)
Thanks for informative article. It help me a lots.