https://github.com/na1307/blazor-github-pages
Prepare Blazor WASM for GitHub Pages
https://github.com/na1307/blazor-github-pages
blazor blazor-wasm blazor-webassembly github-pages github-pages-deployment
Last synced: 7 months ago
JSON representation
Prepare Blazor WASM for GitHub Pages
- Host: GitHub
- URL: https://github.com/na1307/blazor-github-pages
- Owner: na1307
- License: mit
- Created: 2024-04-27T00:26:30.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-07T18:12:44.000Z (about 1 year ago)
- Last Synced: 2025-02-07T19:20:34.951Z (about 1 year ago)
- Topics: blazor, blazor-wasm, blazor-webassembly, github-pages, github-pages-deployment
- Language: TypeScript
- Homepage:
- Size: 705 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Pages Blazor WASM
This action allows you to deploy your Blazor WASM app to GitHub Pages.
## Table of Contents
- [GitHub Pages Blazor WASM](#github-pages-blazor-wasm)
- [Table of Contents](#table-of-contents)
- [What this does](#what-this-does)
- [How to use](#how-to-use)
- [1. Set the Project](#1-set-the-project)
- [2. Set the repository settings](#2-set-the-repository-settings)
- [3. Add workflow file](#3-add-workflow-file)
- [Inputs and Outputs](#inputs-and-outputs)
- [Inputs](#inputs)
- [Outputs](#outputs)
- [Troubleshooting](#troubleshooting)
- [Common Issues](#common-issues)
## What this does
Restore, build, and publish the project, modify index.html and 404.html to fit the repository.
## How to use
### 1. Set the Project
Add [`Bluehill.Blazor.GHPages` NuGet Package](https://www.nuget.org/packages/Bluehill.Blazor.GHPages/) to the project.
This Package adds `gh-pages.js` and `404.html` to the published `wwwroot` directory. If these files already exist,
delete them.
Modify `index.html` to include the `gh-pages.js` script. This script adjusts routing for Blazor WebAssembly apps
deployed to GitHub Pages, ensuring the app behaves correctly when navigating subpages.
```html
```
### 2. Set the repository settings
Go to your repository's **Settings > Pages > Source** and set the source to **GitHub Actions**.
This step is crucial for enabling deployments using the GitHub Pages workflow. For reference:
### 3. Add workflow file
Below is an example workflow that deploys your Blazor WebAssembly app to GitHub Pages. Copy these into
`.github/workflows/gh-pages.yml` in your repository.
> **Replace `MyBlazorApp/MyBlazorApp.csproj` with your actual `.csproj` path.**
```yml
name: Deploy GitHub Pages
on:
# Runs on pushes targeting the default branch
push:
branches: [ "main" ]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: 9.0.x
- name: Prepare Blazor WASM for GitHub Pages
uses: na1307/blazor-github-pages@v3
id: prepare
with:
project-path: MyBlazorApp/MyBlazorApp.csproj
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ${{ steps.prepare.outputs.wwwroot-path }}
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```
## Inputs and Outputs
This action has two inputs and one output.
### Inputs
`project-path`: Path of project (.csproj). Required, no default value. For example: `MyBlazorApp/MyBlazorApp.csproj`.
`publish-path`: Path to output in the Publish step. Most of the time, you can leave this as the default `_out`. However,
you can specify a custom path if needed for your project structure or workflow requirements.
> **Note:** Inputs `main-repo` and `fix-404` have been **deprecated** as of version v3.
> This action now:
> - Automatically detects if the repository is the default Pages repository (username.github.io).
> - Modifies `404.html` if it exists.
### Outputs
`wwwroot-path`: The resulting `wwwroot` path. It must be passed to `path` in the `upload-pages-artifact` action.
## Troubleshooting
### Common Issues
1. **`wwwroot` Path Not Found**
- Ensure the Blazor project builds and publishes successfully.
- Verify that the `publish-path` input matches the expected output directory.
2. **Deployment Fails**
- Ensure that your repository’s Pages Source is set to **GitHub Actions**.
- Check the logs in the **Deploy to GitHub Pages** step for detailed error messages.
3. **Routing Issues**
- Confirm that `gh-pages.js` is included in `index.html` as shown in [Step 1](#1-set-the-project).
For additional support, file an issue in the [GitHub repository](https://github.com/na1307/blazor-github-pages).