Azure Static Web Apps add first class support for modern, fast and responsive websites inside the Azure portal. The integration allows you to create and deploy a web site very fast with little configuration.
Please Note: This post is based on the preview version of static web apps and some features may have changed. Since this post was written static web apps now support apex domains, Azure DevOps and a CLI amongst other things. Check out the official docs for more details.
What is a Static Web App
Traditional web applications, such as those based on ASP.net generate pages on the web server with each request. These pages may be cached however the initial fetch of the page can be slow. Static sites are an alternative approach and fall into two categories.
There are many different site generators however I have been using Gatsby, a React based generator for just over a year and it has a large community with many plugins and themes.
What are Azure Static Web Apps
A feature of Azure I have utilised heavily over the years has been Azure Static Website not to be confused with the new Azure Static Web Apps. Azure has had static website hosting for some time with storage accounts. You enable the feature under the blob storage account, place you files in the
$web folder and you have a website.
While Azure Static Websites are a great feature you need to attach to either an Azure front door or an Azure CDN if you want to use SSL, set http headers, utilize caching, or have any server side redirects. There also are some features which it just cannot support.
Azure Static Web Apps (currently in preview) solves these issues and brings everything together in addition to setting up a full build and deploy pipeline for you.
Creating a Static Web App
Before you can deploy a static web app you need a GitHub repository with a site code ready to publish. If you have this already you can skip head otherwise read on.
1. Create the Application
There are many static site generators (Over 300 on jamstack.org) however it is worth noting that currently Azure Web Apps have build presets for only three static site generators; Gatsby, Hugo and VuePress. If you are using another you will need to provide your own build script.
For this tutorial we will use Gatsby, one of the most popular react based generators.
You will first to setup your local machine with Gatsby and once setup you can run one of the many starter sites. For this blog for example I have used the Novela starter which can be created using this command:
1gatsby new novela-site https://github.com/narative/gatsby-starter-novela
As with all Gatsby sites you can then run this locally using the develop command:
2. Create a Github Repository
At the moment Azure Static Web Apps require your code and build script to stored in GitHub however they have said that they will be expanding this to DevOps soon.
Create a new Github repository and push up your gatsby site. Azure Static Web Apps support both private and public repositories so you can select either. You can skip the readme and gitignore options as these are part of the starter application you already have.
3. Create a Static Web App in Azure
Creating the app in Azure is the simplest part of the process. In the Azure portal navigate to “Create Resource” and select “Static Web Apps”, or jump to the create page.
When prompted enter the name and select both the region and resource group. As this feature is in public preview not all regions are available yet.
The next step is to connect your GitHub account and select both the repository and branch.
As part of this process it will set up GitHub Actions to automatically build and publish your web app when code is committed. For this to work you will need to define a few details. As we are using Gatsby static site generator we will select this and the app location, api location and output are auto populated for us.
Once “Create” is clicked the site will be generated and you will then be able to browse to it.
4. Domain Names
To attach a domain name from the portal when looking at your static web app select “Custom Domains” then click “Add”. You are then given a CName entry to add to you DNS record.
A SSL certificate is manged for you and HSTS is turned on so you don’t need to worry about these.
5. 404 Pages and Redirects
Azure looks for this file in a variety of locations dependant on the framework you are using. Gatsby is based on react so we can add it to the static folder which will copy it into the public folder as part of the build.
By default even though our Gatsby app can handle 404s gracefully they are intercepted by the Static Web App and a default page is shown. Placing an entry in our routes.json file fixes the issue.
2 "routes": ,
3 "platformErrorOverrides": [
5 "errorType": "NotFound",
6 "serve": "/404"
9 "errorType": "Unauthenticated",
10 "statusCode": "302",
11 "serve": "/login"
There is a lot that can be done with the routes file including adding default http headers and setting the mime type. The routes however are relative and cannot be based on hostname and only default headers for all requests can be added.
Although I am not covering these in detail it is worth mentioning that you can host Azure functions as part of the same static web app. As they are integrated this means they require no CORS configuration.
In this post we have looked at what static web apps are and how using the preview feature in Azure we can take a Gatsby starter template and deploy this with a custom domain.
Title Photo by glenncarstenspeters on Unsplash.