Blazor WASM Publishing to GitHub Pages

Blazor WASM Publishing to GitHub Pages


20 Articles


In this article, let's learn about Publishing Blazor apps to GitHub Pages.

Table of Contents

  1. Introduction
  2. Publishing to GitHub Pages
  3. Summary


With ASP.NET Blazor WebAssembly (WASM) you can create .NET web applications that run completely inside of the browser sandbox. The publish output of a Blazor WASM project are all static files. Now that you can run .NET web applications without server-side code, you can deploy these applications to various static site hosts, such as Azure Static Web Apps and GitHub Pages. With the Blazor WebAssembly hosting model:

  • The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser in parallel.
  • The app is executed directly on the browser UI thread.

Publishing to GitHub Pages


  1. Create a Blazor Wasm Project.
  2. Add PublishSPAforGitHubPages.Build Nuget Package.
  3. Application source code must be inside of a GitHub repository. So, you need to create a local Git repository and commit your source code to the repository using these commands.

    Code Sample - Create Local Repository

Push Blazor Project to GitHub

Create a new GitHub repository (instructions) and copy the commands to "push an existing repository from the command line" from the empty GitHub repository page, here's what it should looks like but with a different URL:

Code Sample - Push to GitHub Repository

Create a GitHub Actions Workflow

Now that your source code has been pushed to GitHub, you'll need to create a GitHub Actions Workflow that builds your project, commits the output and pushes the code to a separate GitHub branch. GitHub Pages will use this separate branch (usually named 'gh-pages') as the static files for your site.

Start by navigating to the Actions tab in your GitHub repository and click on the link 'set up a workflow yourself':

create github actions workflow

Clicking that link will take you to the 'Edit new file' page. The file that you are about to create will instruct GitHub Actions how to build and deploy your project using YAML.These Workflow YAML files will be stored under the folder '.github/workflows/'.

Note: Check out the GitHub Actions documentation to learn more about creating workflows.

On the right side you can browse the GitHub Actions marketplace and read documentation. The GitHub Actions marketplace already has a ton of pre-made actions so you don't have reinvent the wheel. For example, when you search for '.NET', the first result is 'Setup .NET Core SDK' which is an action provided by the GitHub organization. You'll be using this action in the next steps.

configure github actions workflow

Delete all code in this file so you can build your workflow from scratch. The first line you'll need to add is the 'name' property. Give a meaningful name for your workflow:

Code Sample - Give a meaning name

Next, you need to specify what will trigger the workflow. Add the following lines:

Code Sample - Setup Trigger

These lines instruct GitHub Actions to run your workflow on every git push and pull request to the main-branch.

Now, you must configure your jobs, and which image each job will run on. Give your job a meaningful name following the kebab-case naming convention such as deploy-to-github-pages.

Configure your job to run on Ubuntu by adding runs-on: ubuntu-latest, and add an empty steps property.

Code Sample - Setup Job

The first step to add will be using the checkout action provided by GitHub. Without passing any parameters to the action, the checkout action will by default perform a git checkout against your main branch.

Code Sample - Setup Job

Once this action is performed, your code will be available to work with.

To build and publish the Blazor application, you'll also need to have the .NET Core SDK which doesn't come pre-installed with the Ubuntu machine. Using the setup-dotnet action provided by GitHub, you can easily install the .NET SDK on top of the Ubuntu machine:

Code Sample - Setup .NET

By passing in the dotnet-version parameter, you can specify which version of the .NET SDK you want to install.

Next install wasm-tools workload to enable aot on publish. Using the run property, you can specify which commands to execute. Add a run property with value of your dotnet workload install wasm-tools command.

Code Sample - Install WASM Tools Workload

Now that the .NET Core SDK is installed, you can run the dotnet publish command to build and deploy your Blazor app. Using the run property, you can specify which commands to execute. Add a run property with value of your dotnet publish command.

Code Sample - Publish Project

  • Using the -c (--configuration) argument, you can tell to build the project using the Release configuration.
  • Using the -p (--configuration) argument, you can tell to publish the project for GitHub Pages deployment. This will generate necessary files like 404.html, nojeykyll and rewrite the base url in all pages to match to your github username.
  • Using the -o (--output) argument, you can specify where to put the published files. Tell dotnet to publish the project to the dist/Web folder.
  • The --nologo argument will prevent some unnecessary lines from being output to the console.

Now that you have successfully published the project to the 'dist/Web' folder, you can use another very helpful action from the marketplace called 'github-pages-deploy-action'. This action will make it easy to publish your static files to GitHub Pages.

Code Sample - Commit to GitHub Pages

  • The ${{ secrets.GITHUB_TOKEN }} resolves to a token used for securely communicating with GitHub on your behalf. This token is available by default in all workflows and permissions are limited to the repository that contains your workflow. By passing it into the GITHUB_TOKEN property, the action can use it to create and push to the 'gh-pages' branch.
  • The BRANCH property will configure which branch the action will create and push to. Set this to 'gh-pages'.
  • The FOLDER property will configure which folder and files will be pushed to the 'gh-pages' branch. Set this to 'dist/Web/wwwroot'. This is where the project will be published, and all the static resources are in the wwwroot-subfolder.

Now that all steps are in place, commit the file:

commit github actions workflow

Navigate back to the GitHub Actions overview page by pressing the "Actions" tab.

github actions workflow created

You can now find your GitHub Action Workflow and the workflow runs on this page. Click on your first run which was automatically created when you committed the workflow, and watch it publish your project to the 'gh-pages' branch:

github actions workflow run completed

Once completed, you can see the result by navigating to the 'gh-pages' branch in your repository:

gh-pages branch

The last step is to enable GitHub pages in the repository settings. Navigate to the settings by clicking on the 'Settings' tab. Scroll down to the 'GitHub Pages' section and select the 'gh-pages' branch in the 'Source' dropdown.

github pages

After a few seconds to a minute, the GitHub Pages site should be available at '[YOUR_USERNAME][YOUR_REPOSITORY_NAME]'.

Here is the complete workflow configuration:

Code Sample - Complete GitHub Pages Workflow

Configure CNAME

You can also use custom domain to load your blazor wasm app.

  1. Purachse your custom domain.
  2. Add <GHPagesBase>/</GHPagesBase> property in your .csproj.
  3. Add a CNAME file with your domain name as content and commit in gh-pages branch.
  4. Configure GitHub IP Address in your DNS Settings from your domain provider. You can leanr more about configuring custom domain for your GitHub Pages from here.
  5. Add your domain name in the custom domain text box in github pages configuration.
  6. After some time your site will be published under your domain.


Blazor WebAssembly can be served as static files. These files can be hosted in static hosting sites such as GitHub Pages. Using GitHub Actions you can create a workflow to automatically deploy the Blazor application to GitHub pages.

  • Blazor
  • Publishing
  • GitHub Pages
  • GitHub
  • CI/CD
  • Continuous Integration
  • Continuous Deployment