on:  Static websites
Search
List of notes
Published: August 2025
This article is part of a series on: Configuring Azure static web apps.
  1. Create a new Static Web App
  2. Use a custom domain
  3. Authorisation configuration
  4. Blocking an authentication provider
  5. Become co-owner of a subscription
  6. API configuration

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.

Note that the URL of additional environments are derived from the subdomain of the production environment and can be guessed once a custom domain is assigned.

Assign a custom domain

  • Go to the Static Web App section of the Azure portal.
  • Select the static web app in the list of apps.
  • Find the environment in Settings | Environments
  • Click right on the Browse and copy the URL of the subdomain.
  • My custom domains are managed by an external provider, so what I have to do:
    • Go to the provider's DNS administration
    • Add a CNAME record with the subdomain (www or something else) as name and the subdomain URL for the environment as value. You probably need to add a dot/period to the URL.
    • Make sure to publish the changes in the DNS to the world.
  • Go back to the Azure portal
  • Go to Settings - Custom domains
  • Add a new custom domain and add the full subdomain (e.g., www.yourdomain.tl). This makes Azure accepts the redirected traffic.

Limitations

There are two limitations in 2025. One is a maximum of custom domains per Static Web App (2 in the free plan in 2025, 6 in other plans). But more importantly: the custom domain can only be assigned to the production domain. It is not possible to assign a custom domain for a second environment, e.g., for a test environment or a private version of the website. You'd have to use the generated subdomain URL to access those environments.

For me that is an inconvenience for testing, but as static websites can also be tested with a local webserver on a development machine I only need a test environment in Azure if I want to include the pipeline in the tests.

It is a deal breaker for hosting the private version of the website, so I use a separate Static Web App for that.