As a follow-up on the presentation I did at CloudBrew about Azure Static Web Apps I want to write a series of blog posts.
- Part I - Using the VS Code Extension
- Part II - Using the Astro Static Site Generator
- Part III – Deploying to multiple environments
- Part IV – Password protect your environments
- Part V – Traffic splitting
- Part VI – Authentication using pre-configured providers
- Part VII(this post) – Application configuration using staticwebapp.config.json
Before I continue with the authentication and authorization part, I want to take a side step into configuration. When talking about configuring a static web app, we have to make a difference between:
-
Application configuration: This allows us to configure the application behavior and features and is managed through the
staticwebapp.config.jsonfile. Use this file to define route and security rules, custom headers, and networking settings. -
Build configuration: Tweak the build process.
-
Application settings: Change application-level settings and environment variables that can be used by backend APIs.
Conceptually you can see an Azure Static Web App as a reverse proxy with behind it storage for your static content and an (optional) API. We can configure and tweak the rules of this reverse proxy through our staticwebapp.config.json file.
Azure Static Web App will look for this file in the folder set as the app_location or any subfolder. Additionally, if there is a build step(like for an Angular or React app), you must ensure that the build step outputs the file to the root of the output_location.
An example file looks like this:
You can configure a lot of settings in this file but I’ll focus on 2 specifically for this post:
- "routes" - are an array of "route" objects that can each be associated with access rules ("allowedRoles"), actions ("redirect", "rewrite") - and request ("methods") and response ("headers","statusCode") properties.
- "navigationFallback" supports applications that rely on client-side routing by providing a server-side fallback route which serves the required page, with filters to control usage.
I always start by configuring a navigationFallback. This guarantees that any URL that doesn’t match to a specific route rule can be handled. This is especially important when you are hosting an SPA and you want to redirect the user to the entrypoint of your SPA(typically an index.html file):
Another thing you’ll certainly use are the routes. Here we get a lot of power in our hands. For every route we can configure:
- A route pattern: rule to check if a request matches the specified route, e.g.
"/articles/*.html" - A list of AllowedRoles: defines an array of role names required to access a route. e.g.
["authenticated"] - A Rewrite property: defines the file or path returned from the request . The browser url doesn’t change and the URL is rewritten behind the scenes.
- A Redirect property: defines the file or path returned from the request. The user is redirected to the target path using a 302 response.
Remark: There is a lot more we can configure, but I'll handle these settings when needed in a later post.
More information
Configure Azure Static Web Apps | Microsoft Learn
Configuration overview for Azure Static Web Apps | Microsoft Learn