How to deploy Blazor WebAssembly to Cloudflare Pages
Tags: dotnet, blazor, cloudflare
Published: 2021-03-20 04:06:57

---
title: How to deploy Blazor WebAssembly to Cloudflare Pages
published: true
date: 2021-03-14 00:00:00 UTC
tags: dotnet, blazor, cloudflare
canonical_url: https://swimburger.net/blog/dotnet/how-to-deploy-blazor-webassembly-to-cloudflare-pages
cover_image: https://swimburger.net/media/jvhfzhwh/blazor-cloudflare-pages-social.png?anchor=center&mode=crop&width=1000&height=420
---

With ASP.NET Blazor WebAssembly (WASM) you can create .NET web applications that run completely inside of the browser sandbox. The published output of a Blazor WASM project are **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 the brand-new [Cloudflare Pages](https://pages.cloudflare.com/)**.

Here are some other tutorials if you're interested in hosting Blazor WASM on other static site hosts:

- [Azure Static Web Apps](https://swimburger.net/blog/dotnet/how-to-deploy-aspnet-blazor-webassembly-to-azure-static-web-apps)
- [GitHub Pages](https://swimburger.net/blog/dotnet/how-to-deploy-aspnet-blazor-webassembly-to-github-pages)
- [AWS Amplify](https://swimburger.net/blog/dotnet/how-to-deploy-blazor-webassembly-to-aws-amplify "How to deploy Blazor WebAssembly to AWS Amplify")
- [Firebase Hosting](https://swimburger.net/blog/dotnet/how-to-deploy-blazor-webassembly-to-firebase-hosting)
- [Netlify](https://swimburger.net/blog/dotnet/how-to-deploy-blazor-webassembly-to-netlify "How to deploy Blazor WebAssembly to Netlify")
- [Heroku](https://swimburger.net/blog/dotnet/how-to-deploy-blazor-webassembly-to-heroku "How to deploy Blazor WebAssembly to Heroku")

This walkthrough will show you how to deploy Blazor WASM to Cloudflare Pages. Cloudflare Pages is a brand-new service by Cloudflare to host static websites. Cloudflare Pages integrates with GitHub to pull down your code from your repositories, then builds your website on their build platform, and uploads the resulting static files to their static hosting service. **The biggest benefit of using Cloudflare is that your site will be backed by their global CDN, and Cloudflare is outstanding at speed and scale.**

This guide will walk you through these high-level steps:

1. Create Blazor WebAssembly project
2. Commit the project to a Git repository
3. Create a new GitHub project and push the Git repository to GitHub
4. Create a new Cloudflare Pages website

**Prerequisites** :

- .NET CLI
- Git
- GitHub account
- Cloudflare account (free tier is sufficient)

**You can find the [source code for this guide on GitHub](https://github.com/Swimburger/BlazorWasmCloudflarePages).**

## Create Blazor WebAssembly project

Run the following commands to create a new Blazor WASM project:

```powershell
mkdir BlazorWasmCloudflarePages
cd BlazorWasmCloudflarePages
dotnet new blazorwasm
```

To give your application a try, execute `dotnet run` and browse to the URL in the output (probably https://localhost:5001):

```powershell
dotnet run
# Building...
# info: Microsoft.Hosting.Lifetime[0]
# Now listening on: https://localhost:5001
# info: Microsoft.Hosting.Lifetime[0]
# Now listening on: http://localhost:5000
# info: Microsoft.Hosting.Lifetime[0]
# Application started. Press Ctrl+C to shut down.
# info: Microsoft.Hosting.Lifetime[0]
# Hosting environment: Development
# info: Microsoft.Hosting.Lifetime[0]
# Content root path: C:\Users\niels\source\repos\BlazorWasmCloudflarePages
# info: Microsoft.Hosting.Lifetime[0]
# Application is shutting down...
```

Optional: You can use the `dotnet publish` command to publish the project and verify the output:

```powershell
dotnet publish
# Microsoft (R) Build Engine version 16.8.0+126527ff1 for .NET
# Copyright (C) Microsoft Corporation. All rights reserved.
# 
# Determining projects to restore...
# All projects are up-to-date for restore.
# BlazorWasmCloudflarePages -> C:\Users\niels\source\repos\BlazorWasmCloudflarePages\bin\Debug\net5.0\BlazorWasmCloudflarePages.dll
# BlazorWasmCloudflarePages (Blazor output) -> C:\Users\niels\source\repos\BlazorWasmCloudflarePages\bin\Debug\net5.0\wwwroot Optimizing assemblies for size, which may change the behavior of the app. Be sure to test after publishing. See: https://aka.ms/dotnet-illink
# Compressing Blazor WebAssembly publish artifacts. This may take a while...
# BlazorWasmCloudflarePages -> C:\Users\niels\source\repos\BlazorWasmCloudflarePages\bin\Debug\net5.0\publish\
```

In the publish directory, you will find a web.config file and a wwwroot folder. The config file helps you host your application in IIS, but you don't need that file for static site hosts. **Everything you need will be inside of the wwwroot folder. The wwwroot folder contains the index.html, CSS, JS, and DLL files necessary to run the Blazor application**.

## Push Blazor project to GitHub

For this walkthrough, your application source code must be inside of a GitHub repository.  
First, you need to create a local Git repository and commit your source code to the repository using these commands:

```powershell
# 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"
```

Create a new GitHub repository ([instructions](https://docs.github.com/en/github/getting-started-with-github/create-a-repo)) and copy the commands to "push an existing repository from the command line" from the empty GitHub repository page, here's what it should look like but with a different URL:

```powershell
git remote add origin https://github.com/Swimburger/BlazorWasmCloudflarePages.git
git push -u origin main
```

## Create the Cloudflare Pages website

Log in to Cloudflare and click on the Pages-link on the right side: 

 ![Cloudflare Dashboard where the Cloudflare Pages link is pointed at](https://swimburger.net/media/j4ibxtdg/cloudflare-home.png)

On the next screen click on the "Create a project" button:

 ![Screenshot of Cloudflare Pages homepage featuring a button &quot;Create a project&quot; with a pointer hovering over it](https://swimburger.net/media/01jmtapv/1.png)

You will need to give Cloudflare access to your GitHub repositories if this is your first time setting up a Cloudflare Pages website. Click on the "Connect GitHub account" button and give Cloudflare access to your GitHub repositories. At a minimum, you need to give Cloudflare access to the repository you want to deploy.

 ![Screenshot of Cloudflare asking you to connect your GitHub account to Cloudflare](https://swimburger.net/media/oiodauyp/2.png)

After giving Cloudflare access to your GitHub account, Cloudflare will prompt you to select the repository you want to deploy.  
Select the GitHub repository you created earlier and click on the "Begin setup" button:

 ![Cloudflare Pages lists all the GitHub repositories asking you to select the repository you want to deploy](https://swimburger.net/media/n0ynfaez/3.png)

The next screen prompts you for a bunch of information:

- **Project name** : this name will be used to generate the subdomain under the pages.dev domain
- **Production branch** : this is the branch that will be used to build the production website. This should be "main", "master", or whatever your main branch name is.
- **Framework preset** : Cloudflare Pages has a lot of presets to make the setup easier. There's no official support for .NET and also no framework preset. You can leave this to none.
- **Build command** : This is the most important setting. In this setting, you can tell Cloudflare Pages which commands to run to build your static website. Since .NET isn't installed on the build environment, you'll first need to install .NET and then publish your Blazor WASM project. Unfortunately, this is a single-line text field, but you can enter multiple commands separated by ";".  
Copy/paste the following commands into the "Build command" field:  

```bash
curl -sSL https://dot.net/v1/dotnet-install.sh > dotnet-install.sh;
chmod +x dotnet-install.sh;
./dotnet-install.sh -c 5.0 -InstallDir ./dotnet5;
./dotnet5/dotnet --version;
./dotnet5/dotnet publish -c Release -o output;
```

This script does the following:

  - 

The **curl** command downloads a shell script to install the .NET SDK provided by Microsoft.

  - 

The **chmod** command changes the permission of the shell script to allow execution of the script.

  - 

The ' **dotnet-install.sh**' script installs the .NET SDK:

    - 

The **-c** argument tells the install script to install .NET **version 5.0** which is the version I am using. Change 5.0 to your version if you're using a different version.

    - 

The **-InstallDir** argument will instruct the script to install the SDK in a specific directory. In this case it will create a directory called 'dotnet5' and put the SDK there.

  - The `dotnet --version` command will print the version of the .NET SDK to verify the successful installation of the .NET SDK. Note how it is invoking the dotnet CLI from the 'dotnet5' folder where the .NET 5 SDK was installed by the 'dotnet-install.sh' script.
  - The `dotnet publish` builds & publishes the Blazor WASM project:
    - The **-c** argument tells the CLI to build in Release configuration.
    - The **-o** argument tells the CLI to put the output in the '_output_' folder.
- **Build output directory** : Using this setting you can specify which folder should be deployed to Cloudflare Pages. Set this to ' **_output/wwwroot_**' because that's where the Blazor WASM project will be published to.
 ![Screenshot of the Cloudflare Pages build and deployment settings](https://swimburger.net/media/2gadhk3o/4.png)

Note: There are some more settings that have been omitted from the above list and screenshot to keep things shorter.

Fill out the form as specified in the above screenshot and list. Click on the "Save and Deploy" button.

Cloudflare Pages will now build and deploy your Blazor WASM application. The output of this process will be shown in real-time.  
Once the build & deploy process is completed, the URL of your website will be shown at the top right:

 ![Screenshot of the Cloudflare Page website dashboard after a successful build &amp; deploy](https://swimburger.net/media/rg1nnvsz/6.png)

Click on the link of your website and verify whether your Blazor WASM application is working as expected. It should.  
Unlike many other static site hosts, there's no need for any additional configuration changes because of [the sensible defaults](https://developers.cloudflare.com/pages/platform/serving-pages) chosen by Cloudflare. 

Out of the box, Cloudflare Pages will provide SPA rewrite functionality:

> If your project doesn't include a top-level `404.html` file, Pages assumes that you're deploying a single-page application. This includes frameworks like React, Vue, and Angular. **Pages' default single-page application behavior matches all incoming paths to the root (****`/`), allowing you to capture URLs like `/about` or `/help` **** and respond to them from within your SPA.**  
> Source: [Serving Pages by Cloudflare](https://developers.cloudflare.com/pages/platform/serving-pages)

Unfortunately, Cloudflare Pages does not come with .NET support out of the box. As a result, you have to install .NET as part of the build process which slows down the build & deployment.

## Bonus: Pull Request Previews

Cloudflare Pages has built-in support for creating preview environments for your pull requests. When you create a Pull Request on GitHub, you will see Cloudflare Pages building right from the pull request.  
When the build & deploy has completed, Cloudflare Pages will add a comment on your Pull Request with the status and URL to your preview environment:

 ![Screenshot of Pull Request where Cloudflare Pages has left a comment after finishing the build &amp; deployment](https://swimburger.net/media/ikcbc0d0/gh.png)

You can also find the preview build & deploy on your Cloudflare Pages website dashboard with the label "Preview":

 ![Screenshot of a preview build &amp; deploy on Cloudflare pages](https://swimburger.net/media/qvxfrqau/7.png)
## Summary

Blazor WebAssembly can be served as static files. These files can be hosted in static hosting services such as Cloudflare Pages. You can create a new Cloudflare Pages application using GitHub as the source code provider. Cloudflare Pages's does not contain .NET build tooling so you have to install them yourself during the build process. Once installed, you can run the publish command to build & publish your Blazor WASM application and tell Cloudflare Pages to deploy the resulting static assets.