Static websites

API to go with a website

Sometimes there is a need to have some code running on the server. It is possible to do that to some extent for a Static Web App via the API mechanism, but that is not always free and there are limitations on the API implementation.

API configuration

To use the API, the code of the API has to be provided and the configuration of the Static Web App has to be modified.

Adding search to a static website

Some websites, like this one, are hard to navigate if there is no way to search the site. Search also requires (at least) client-side code to display the search results. What are the options for a static website?

Markdown rules!

It appears that almost all websites that publish text in some form use Markdown as the format to write texts in. The first website for one of my projects already did that in 2010. At that time the conversion of markdown to web page required a lot of programming. Surely that must be different in 2025. What's the best way to do that?

Running custom tools

As I'm using a custom tool to convert content in markdown to a website, the Azure pipeline has to run tools that are not part of the out-of-the-box task catalogue. How to do that, and should we should use Ubuntu or Windows for the pipeline?

Ubuntu or Windows revisited

When running custom tools in a pipeline, it is [best to choose Windows](200 Custom tools.md#vmimage) as the virtual machine image. There's one catch: unlike many of the standard Azure-related tasks is the task to publish to a Static Web App designed for Linux only. Bummer, Microsoft definitely wants to discourage the use of Windows images. But there is a workaround!

Use git in pipelines

By default a pipeline takes its content from a clone of a branch of the git repository. Once the pipeline has completed, the clone is discarded. Sometimes the creation of the website updates content or derived files, e.g., a list of all external resources the website links to, and the changes should be kept. Or you want to push pipeline results to another branch or even repository. How to use git within a pipeline?

Scheduling pipelines

Most examples of pipeline specifications demonstrate how to start a pipeline when new content is available. But there are other tasks to be done for a website. E.g., validate that external resources the website links to are still available, or retrieve data from external sources and add it to the content. Pipelines can be used for that as well.

Pipeline notifications

Out of the box the owner of a subscription gets notifications about every pipeline that is run. That is too much: you'll get a notification every time new content for a website is pushed to Azure. It is good enough to be notified when the pipeline fails, or if one of the steps in the pipeline requires attention.

Become co-owner of a subscription

I already had an Azure subscription as a professional before I started using it for personal projects. For some personal/hobby projects it is best to have a separate subscription. But it is quite inconvenient to login/logout all the time just to access the Azure portal to access a different subscription. Especially as I'm currently the only person who is managing the personal/hobby subscriptions. There is no need for that: you can manage all subscriptions using the same account.

Limitations

The free plan for personal/hobby websites has some limitations. Most are limits on the capabilities of Static Web Apps rather than of the free plan.

Authorisation

Static Web Apps support role-based authorisation. The end users of the website should be divided based on the role they have in the application. For each route or path of the web pages (that can include wildcards) the roles can be listed of the end users that have access to that page (or pages).

Authorisation configuration

There are two parts: page authorisation and user administration. And you can decide whether the authorisation is added in the source or as part of the publication process.

Blocking an authentication provider

According to the documentation it is possible to block an authentication provider. That is a sensible thing to do. Twitter and later X was among the default providers, and given its owner/CEO and his (non-)concerns for the well-being of its users/customers, that's not one I would trust to be really safe and have no hackable backdoor. The safest option would be to block all providers except the ones you really are going to need. But that is a challenge as the Static Web App authentication seems not to be designed with such security in mind.

What about staging?

Before your files end up on the publicly available domain, you may want to test it on a separate environment. Or you may want to have multiple versions of the website. This is facilitated within the same Static Web App.

What is a static web app?

An Azure Static Web App is a way to host a static website that consists of web pages, images and other resources that are static/fixed, they have been created before the website is deployed to the hosting location.

The first time working with an Azure Static Web App is a bit confusing. There are a lot of websites and videos that offer a click-through for the various tools and interfaces. But I couldn't find a more conceptual description how it works, which components must be involved and where design decisions can be made. So let's write it down for a future me.

Create a new Static Web App

Most descriptions show how to create a new Static Web App as click-through and assume that the source of the website is in a Github or Azure DevOps git repository. But the source actually is not relevant for the creation of the Static Web App proper.

Here is the description for the first step: creating the Static Web App.

Use a custom domain

By default Azure creates a unique URL for each environment: a subdomain of .azurestaticapps.net. The URL cannot be guessed, so a published website stays hidden from people without knowledge of the URL. A custom domain can be assigned even before the website has been published.

Publish to a static web app from a git repository

In the Azure portal it may be possible to create a Static Web App and a pipeline to publish to it at the same time. I find it easier to split the two actions and [create the Static Web App](110 Create SWA.md) first. In all of my projects the pipeline has to do much more than just publishing a few files to Azure. It does not make sense to combine the actions; it is more efficient to create the pipeline separately.

Typical architecture for publish-only websites

The various free offerings for the deploying and hosting of (static) websites can be taken as a starting point for the architecture of an application. For all my personal projects the architecture follows the same pattern.

The case for static websites

Part of the investigation of the options to modernize the Waar is Frank? website was to keep an open mind about the architecture of the website.

A bit to my surprise a solution based on a static website turned out to be the easiest to work with. That is mainly because of a few major technological advances, imho:

• Small-scale hosting is a commodity and is almost free.
• Small-scale hosting is easy if it is publish-only.
• Browsers take care of a lot of device specific headaches.
• Remaining custom software development can be done in one language (.NET everywhere).