I ❤️ .NET

Table of Contents

1. What we gonna do?
2. Why we gonna do?
3. How we gonna do?
4. Summary

What we gonna do?

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

Note: If you have not done so already, I recommend you read the article on Blazor WASM Publishing to IIS.

Why we gonna do?

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.

How we gonna do?

Publishing to GitHub Pages

Prerequisites

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.

   
   # add the gitignore file tailored for dotnet applications, this will ignore bin/obj and many other non-source code files
   dotnet new gitignore
   # create the git repository
   git init
   # track all files that are not ignore by .gitignore
   git add --all
   # commit all changes to the repository
   git commit -m "Initial commit"
                   

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:

git remote add origin https://github.com/ilovedotnet/ilovedotnet.git
git push -u origin master
        

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':

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.

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:

name: build and test and deploy
        

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

# Run workflow on every push to the master branch
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
        

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.

jobs:
  deploy-to-github-pages:
  # use ubuntu-latest image to run steps on
    runs-on: ubuntu-latest
    steps:
        

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.

    # uses GitHub's checkout action to checkout code form the main branch
    - uses: actions/checkout@v4
        

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:

    # sets up .NET Core SDK 6.0.x
    - name: Setup .NET Core SDK
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 8.0.x
        

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.

      # Install dotnet wasm buildtools workload
      - name: Install .NET WASM Build Tools
        run: dotnet workload install wasm-tools
        

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.

      # Publishes Blazor project to the release-folder
      - name: Publish .NET Core Project
        run: dotnet publish ./Web/Web.csproj -c:Release -p:GHPages=true -o dist/Web --nologo
        

• 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.

    - name: Commit wwwroot to GitHub Pages
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        BRANCH: gh-pages
        FOLDER: dist/Web/wwwroot
        single-commit: true # No need of history for publish 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:

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

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:

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

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.

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

Here is the complete workflow configuration:

name: build and test and deploy

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  deploy-to-github-pages:
    runs-on: ubuntu-latest
    steps:
      # Checkout the code
      - uses: actions/checkout@v4

      # Install .NET Core SDK
      - name: Setup .NET Core
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x
          
      # Install dotnet wasm buildtools workload
      - name: Install .NET WASM Build Tools
        run: dotnet workload install wasm-tools
          
      # Publishes Blazor project to the release-folder
      - name: Publish .NET Core Project
        run: dotnet publish ./Web/Web.csproj -c:Release -p:GHPages=true -o dist/Web --nologo

      - name: Commit wwwroot to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          BRANCH: gh-pages
          FOLDER: dist/Web/wwwroot
          single-commit: true # No need of history for publish branch
       

Configure CNAME

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

1. Purchase your custom domain.
2. Add <GHPagesBase>/</GHPagesBase> property in your .csproj.
3. Add a CNAME file with your domain name ilovedotnet.org as content and commit in gh-pages branch.
4. Configure GitHub IP Address in your DNS Settings from your domain provider. You can learn 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.

Summary

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.