How to set a custom URL for an Azure Static Web App

This site runs on Azure Static Web Apps on the Free plan. Out of the box, Azure hands you an autogenerated address like black-pond-097a9a910.7.azurestaticapps.net. That works, but it isn’t the name you want on a business card. Here’s how I point a real domain at it — and the good news is Azure issues and renews free SSL/TLS certificates for every custom domain you add, so you get HTTPS for nothing.

There are two cases worth knowing: the www subdomain and the apex (root) domain. Most people want both.

First, know your two names

Given www.example.com:

• www is the subdomain.
• example.com is the apex (or root) domain.

They’re configured differently because of how DNS works: a CNAME record maps a name to another name (great for www), while the apex generally can’t use a plain CNAME and needs an ALIAS/ANAME record, CNAME flattening, or an A record.

Setting up the www subdomain (CNAME)

This is the simplest path and works with almost any registrar.

1. In the Azure portal, open your static web app and copy the generated URL from the Overview pane.

2. Sign in to your domain registrar and open its DNS settings.

3. Add a CNAME record:

   Setting	Value
   Type	CNAME
   Host	www
   Value	your *.azurestaticapps.net URL
   TTL	leave the default

4. Back in the portal, go to Settings → Custom domains → + Add → Custom domain on other DNS. Enter www.example.com, choose CNAME as the hostname record type, and select Add.

Azure verifies the record exists in public DNS, then provisions the certificate. Propagation depends on your record’s TTL and can take anywhere from a few minutes to a couple of days.

Setting up the apex domain

The apex is the fussy one. Your options, best-performance first:

• ALIAS / ANAME record — if your registrar supports it. Keeps you on Azure’s global distribution.
• A record — a fallback that pins you to a single regional host, so you lose global distribution. Only use it if you have to.
• Azure DNS — move your domain’s DNS to Azure and it wires the apex up for you automatically. This is the cleanest option if your registrar (looking at you, GoDaddy and Squarespace) won’t do ALIAS records.

Whichever you pick, you validate ownership first with a TXT record:

1. In Custom domains → + Add, enter the apex (example.com, no subdomain), choose TXT as the hostname record type, and select Generate code.
2. Copy the generated value and add it at your registrar as a TXT record with host @.
3. Once Azure validates ownership, add the ALIAS record (host @, value = your azurestaticapps.net URL without the https:// prefix). For the A-record path, grab the stableInboundIP from the portal’s JSON View and point an A record at it instead.

Apex changes can take up to 72 hours to fully propagate, so don’t panic if it isn’t instant.

Don’t forget the site config

One thing that’s easy to miss: your generator needs to know its real address so canonical URLs and absolute links point at the right place. In Astro that’s the site field in astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://www.example.com',
});

Update it, commit, and let CI redeploy.

A couple of gotchas

• Custom domains aren’t supported on preview environments — only the production site.
• Unicode / Punycode domains (the xn-- prefix) aren’t supported.
• Migrating a live domain? Validate ownership with a TXT record before you flip the CNAME/A record, so you can move traffic with zero downtime.

That’s the whole thing. Free hosting, free HTTPS, and a name that’s actually yours.