Azure Static Web Apps Frequently Asked Questions

Static Web Apps can automatically build:

• Popular single-page applications (SPA), including: React, Vue.js, Angular, Blazor WebAssembly
• Commonly used static site generators, including: Next.js, Nuxt.js, Gatsby, Hugo, Jekyll, Eleventy

To learn more, see Configure frontend frameworks.

Azure Static Web Apps' build engine is powered by Oryx, which builds your app's frontend and API.

When your app is built, Oryx detects the build steps and executes them automatically. For example, if your app uses Node.js, it installs packages using npm or Yarn. Then, it runs the build or build:azure script provided in your app's package.json file.

If you want complete control over how to build your app, you can configure your own build steps in your app's GitHub workflow or Azure DevOps pipeline. You can then use the Static Web Apps GitHub Actions or Azure Pipelines task to deploy your app. Ensure that you set skip_app_build to true. To learn more, see Build configuration.

The skip_app_build command is currently only supported for the frontend app. The API app must be built by the Azure Static Web Apps GitHub Actions or Azure Pipelines task.

Currently, Azure Static Web Apps supports GitHub Actions and Azure DevOps. More deployment options will be added in the future.

If your app uses create-react-app, its build command treats warnings as errors when running in a continuous integration (CI) environment such as GitHub Actions or Azure Pipelines. If you have warnings in your app, it fails to build. To fix these issues, modify your app to remove the warnings. If you want the build to succeed even if there are warnings, update your build script in package.json to unset the CI environment variable:

"scripts": {
  "build": "CI= react-scripts build"
}

To change the branch to build and deploy from, update the branch names in your app's GitHub workflow. For example, if you want to change your app to build and deploy from a branch named release, update the on section of your workflow:

on:
  push:
    branches:
      - release
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - release

For static web apps created during the preview period, you might need to reset the deployment token.

Azure Static Web Apps' build engine runs in a Linux Docker container, so it can only be run on a Linux build agent.

In your GitHub workflow, configure the actions/checkout Action to enable LFS:

- uses: actions/checkout@v2
  with:
    submodules: true
    lfs: true

Azure Static Web Apps automatically handles cache invalidation. When a deployment completes, all requests are served the latest version of your files. However, files can still be cached in your users' browsers or in a CDN if you've configured one. To control how browsers and CDNs cache your content, configure the appropriate headers in your app's configuration file.

Pre-production environments are currently only supported for GitHub Actions.

You can configure your app to use custom domains, including apex domains. Static Web Apps automatically provides a free TLS certificate when you add a custom domain. To learn more, see Set up a custom domain with free certificate.

You can configure custom error pages using the responseOverrides section of the configuration file.

Azure Static Web Apps is a global service. Your app's static assets are globally distributed. When you create your app, you select a region where the managed Azure Functions app is deployed. If you need your Functions app in a region that doesn't support managed functions, you can use the Bring your own Functions app feature with a Functions app you deploy separately.

Azure Static Web Apps includes global distribution of your app's static assets. If you want to maximize your global footprint or require advanced features, you can add a dedicated content distribution network (CDN) or Azure Application Gateway.

To restrict traffic to a specific CDN, configure your CDN to add a header containing a predefined, secret value to every request, and configure Static Web Apps to require the header. To restrict traffic to an Azure Application Gateway, configure your app to only allow traffic from your Application Gateway's IP.

Also, configure your app to allow forwarding of your CDN or Application Gateway's hostnames.

To learn about configuring Azure Front Door, see this tutorial.

For assets with file extensions of popular text formats, such as .html, .css, and .js, Azure Static Web Apps automatically serves Gzip- or Brotli-compressed versions of your static assets if the client supports it.

For other file types, Static Web Apps allows you to include a Brotli-compressed version of your file with a .br extension. For example, if you have an uncompressed file named app.wasm, you can add a compressed version named app.wasm.br to your app. This version is automatically served if a client that supports Brotli requests app.wasm.

Most frontend frameworks like React, Angular, or Blazor WebAssembly use client-side routing to handle navigation. Client-side routes are only known to the app running in the browser. If you request a client-side route from Static Web Apps, it returns a 404 error because the route doesn't exist in your app's deployed assets. To fix this problem, add a fallback route to your app's configuration file.

There are different types of environment variables that you can set for your app. Configure variables that affect your app's frontend build process in your app's build configuration. To configurate variables that are used by your app's API, use application settings. To learn more, see Configuration overview.

Static Web Apps supports managed identity, but it's only used to retrieve authentication secrets from Key Vault.

If you need managed identity or Key Vault references in your API, use the bring your own Functions app feature to use a separate Functions app that uses managed identity.

Static Web Apps doesn't have a limit on the number of users that can log in to your app. You can assign custom roles to up to 25 users using the built-in invitations system. If you need to assign custom roles to more users, you can use an API function to programmatically assign roles.

You can retrieve the user's access token and claims when you use an API function for role management.

When using Static Web Apps' built-in authentication, users can log in with any of the supported identity providers. If you want to prevent users from logging in with a specific identity provider, you can block it.

If you're using custom authentication, you can configure one or more identity providers.

Static Web Apps' managed function apps don't support all languages or language versions that Azure Functions supports. You can use the bring your own Functions app feature to link a separate Functions app to your Static Web App.

The managed function apps in Static Web Apps are optimized for API scenarios and support only HTTP triggers. If you need to use other trigger types supported by Azure Functions such as for cron jobs or Durable Functions for stateful workflows, you can use the bring your own Functions app feature to link a separate Functions app to your Static Web App.

The Free plan includes many of the same features as the Standard plan such as global distribution, custom domains, free TLS certificates, managed API functions, and more. However, if you need more bandwidth, a service level agreement (SLA), or advanced features, you should consider the Standard plan. To learn more, see Hosting plans and Quotas.

You can upgrade from the Free to Standard plan at any time. You can also downgrade from the Standard plan to the Free plan if you're not using features that require the Standard plan.

Most frontend frameworks provide a development server for running your app locally. However, if you want to use authentication or API functions, it can be difficult to test all the features of your app without deploying it to Azure. To run your app locally, you can use the Static Web Apps command line interface (CLI), which emulates the cloud experience, including authentication, and integrates with the Azure Functions Core Tools to run your API functions. There's also a Static Web Apps Visual Studio Code extension that you can use to deploy your app to Azure.

If you need help or have a suggestion, you can create an issue in the Static Web Apps GitHub repository.

For immediate help with a problem, contact Azure support.