Choose the Right Azure Host for Your Static Site

For most production publishing sites connected to GitHub or Azure DevOps, Azure Static Web Apps is the simpler default. Choose Azure Storage static website hosting when a public blob-backed origin is an intentional part of the architecture. Storage alone has no authentication or authorization, native response-header configuration, or native HTTPS for custom domains without an additional CDN layer (Storage static website documentation).

Select your deployment and hosting requirements; the recommendation updates automatically.

Choose the Hosting Model First

Azure offers two products for hosting static files, but they solve different operational problems:

• Azure Static Web Apps combines static hosting with repository-triggered deployments, custom domains, managed TLS, preview environments, routing and response-header configuration.
• Azure Storage static website hosting serves public files from a blob container. You manage the deployment workflow and add other services when you need custom-domain HTTPS, redirects or headers.

Requirement	Static Web Apps	Storage static website
GitHub or Azure DevOps deployment	Integrated	Build your own pipeline
Managed custom-domain TLS	Yes	Additional CDN required
Redirects, rewrites and headers	Built in	Additional edge service required
Authentication and route authorization	Supported	Anonymous read only
Public files in a blob container	More service than necessary	Good fit
Production tier with SLA	Standard plan	Evaluate complete architecture

The Static Web Apps Free plan is intended for hobby and personal projects and has no SLA. Standard is positioned for general-purpose production workloads and includes an SLA. Limits and prices can change, so use the current Azure pricing page rather than relying on a historical monthly estimate.

Deploy With Azure Static Web Apps

Identify the Deployable Directory

Run the production build locally before creating Azure resources. Record:

• the build command, such as npm run build;
• the source directory;
• the generated output directory, such as dist, build or public;
• whether the output includes 404.html, robots.txt, sitemap files and staticwebapp.config.json.

This prevents a common failure: pointing Azure at source files when it needs generated files, or setting output_location to the wrong directory.

Connect the Repository and Production Branch

Create an Azure Static Web Apps resource, then connect the repository and production branch. Azure can monitor GitHub or Azure DevOps, build when changes reach the watched branch and create staging versions for pull requests (Static Web Apps overview).

Supply the project paths:

• App location: where the front-end source starts, often /.
• API location: leave blank for a static-only website.
• Output location: the generated directory, normally relative to the app location.

Azure creates a GitHub Actions or Azure Pipelines configuration. Treat the resulting YAML file as production configuration. Review the detected framework, branch, paths and build command rather than assuming they are correct.

If an earlier CI step already built the website, point app_location at the generated directory, set skip_app_build: true, and leave output_location empty. Microsoft documents those settings and requires staticwebapp.config.json to be copied into the output directory (build configuration reference).

Configure Caching, Headers and 404 Responses

Ensure staticwebapp.config.json reaches the root of the deployed output. A generated publishing site can begin with this narrow configuration:

{
  "routes": [
    {
      "route": "/assets/*",
      "headers": {
        "Cache-Control": "public, max-age=31536000, immutable"
      }
    }
  ],
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "Referrer-Policy": "strict-origin-when-cross-origin"
  },
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}

Apply immutable caching only to fingerprinted assets whose URLs change when their contents change. Otherwise, a long-lived cached file can remain stale after deployment.

Do not add a single-page application navigationFallback to a generated content site by default. Azure returns the fallback document with a 200 status for unmatched paths not excluded by the rule. On a publishing site, that can conceal broken links and make missing article URLs look like successful pages. Azure’s configuration reference documents route ordering, global headers, error overrides and fallback behavior.

Validate the Azure Hostname Before Changing DNS

Test the generated azurestaticapps.net hostname before attaching production traffic:

1. Open the homepage and representative deep article URLs.
2. Request CSS, JavaScript, images, fonts, robots.txt and sitemap files directly.
3. Check canonical URLs, redirects and trailing-slash behavior.
4. Request a deliberately missing URL and confirm the HTTP response remains 404 while displaying the custom error page.
5. Inspect cache and security headers with browser developer tools or curl -I.
6. Test mobile layouts and client-side interactions.
7. Compare the generated file inventory with the intended release so omitted pages and stale artifacts are visible.

For a migration, put the checks, owners, cutover conditions and rollback trigger in a static website migration runbook.

Attach the Domain and Cut Over

Add the custom domain to the Static Web Apps resource and complete ownership validation before changing the traffic record. Azure automatically provisions free TLS certificates for its generated hostname and added custom domains. Custom-domain DNS must remain publicly resolvable, and the domain must resolve to the static web app over the public internet for automatic certificate renewal (custom-domain documentation).

For a planned migration, lower the relevant DNS record’s TTL in advance and retain the old host until the rollback window closes. Test both the apex and www names.

Choose one canonical hostname. If both names accept traffic, redirect the secondary hostname at an HTTP-capable edge, gateway or redirect service. A DNS record can direct clients to a host, but DNS alone cannot return an HTTP redirect.

Use Azure Storage for a Blob-Backed Origin

Use Storage static website hosting when the site is entirely public and you intentionally want a blob-backed origin.

Create a general-purpose v2 or BlockBlobStorage account, enable Static website, and set the index and error documents. Azure creates a $web container for the generated files. The equivalent CLI setup is:

STORAGE_ACCOUNT="yourstorageaccount"

az storage blob service-properties update \
  --account-name "$STORAGE_ACCOUNT" \
  --static-website \
  --index-document index.html \
  --404-document 404.html

az storage blob upload-batch \
  --account-name "$STORAGE_ACCOUNT" \
  --source ./dist \
  --destination '$web'

Microsoft documents the portal, CLI and PowerShell procedures for enabling the feature and uploading files (Storage deployment guide). The resulting paths are case-sensitive, and the static endpoint serves $web files through anonymous read requests.

After uploading, verify MIME types as well as page responses. Microsoft notes that HTML with an incorrect content type may download instead of rendering. Also decide how the deployment will remove obsolete files: an upload-only command can leave files from an older release in the container.

Storage static hosting cannot itself configure HTTP headers, authenticate visitors or provide HTTPS on a custom domain. If the design immediately adds a CDN or edge service for TLS, caching rules, security headers and redirects, compare that combined architecture with Static Web Apps rather than treating Storage as automatically simpler.