Static Web Apps route rule

Understand the concept

In plain English

A Static Web Apps route rule is an instruction for what should happen when someone requests a particular path. It can protect a route, redirect an old URL, rewrite a request, return a specific status, or support single-page application behavior. Route rules live in staticwebapp.config.json, so they are usually reviewed and deployed with the code. They are not just navigation settings; they decide how the hosted site responds to real user requests. A small route-rule mistake can expose, block, or misroute important pages.

Why it matters

It matters because routing mistakes are some of the easiest Static Web Apps failures to ship and some of the hardest for users to describe. A missing allowedRoles entry can expose private content. An overly broad redirect can create loops. A rewrite can send API traffic to the wrong place. A single-page app can return 404s on direct refresh if fallback behavior and route rules are poorly planned. Route rules give teams precise control, but that control deserves code review and testing. Learners should understand that the visible link structure is not the enforcement layer; the route rule is what Azure evaluates.

Technical context

Technically, route rules are evaluated by the Azure Static Web Apps runtime as part of request handling. They sit inside staticwebapp.config.json and interact with authentication, authorization roles, navigation fallback, response overrides, headers, APIs, and static assets. A route can match public pages, protected dashboard paths, legacy redirects, or /api requests. Operators usually inspect route rules in source control and validate their effects through browser tests, CLI environment checks, and deployment logs. The concept belongs to application configuration, security boundary design, and release validation rather than Azure resource provisioning alone.

Exam context

Compare with

Where it is used

Where you see it

1. In staticwebapp.config.json, where route entries define matching paths, allowed roles, redirects, rewrites, status codes, and related request behavior. during route validation, security review, and release testing.
2. In browser developer tools, where route-rule mistakes appear as 301, 302, 401, 403, 404, rewrite, or redirect-chain behavior. during route validation, security review, and release testing.
3. In pull-request reviews, where configuration changes to protected paths or legacy redirects should be tested before a Static Web Apps deployment. during route validation, security review, and release testing.

Common situations

• Protect dashboard, admin, or partner paths with required roles instead of relying on hidden links.
• Redirect retired marketing or documentation URLs to new routes during a site migration.
• Rewrite friendly front-end paths while keeping file structure or API paths stable.
• Fix single-page app navigation so bookmarked deep links do not return unexpected 404 responses.
• Return clear unauthorized or not-found behavior for users instead of confusing default responses.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Azure CLI

After ten years of Azure engineering, I do not use Azure CLI to edit route rules directly because the rules belong in staticwebapp.config.json and source control. I still use CLI around them constantly. CLI confirms the Static Web App, environment, custom hostnames, users, and linked APIs that receive the deployed rule file. That evidence is crucial when a route works in one preview but fails in production. It also helps operators avoid blaming Azure hosting when the real issue is a repository configuration change. CLI gives the operational context; source control gives the route-rule content. Test this path before approval and record the expected route-rule behavior.

az staticwebapp show --name <static-app-name> --resource-group <resource-group> --output json

az staticwebapp environment list --name <static-app-name> --resource-group <resource-group> --output table

az staticwebapp users list --name <static-app-name> --resource-group <resource-group> --authentication-provider all --output table

az staticwebapp hostname list --name <static-app-name> --resource-group <resource-group> --output table

az staticwebapp backends show --name <static-app-name> --resource-group <resource-group> --output json

Architecture context

Architecturally, route rules are the request policy layer of a Static Web App. I review them the way I review ingress rules, reverse-proxy rules, or lightweight web server configuration. They define which paths are anonymous, which need roles, which legacy URLs are redirected, and how application routes are rewritten. Good architecture keeps rules explicit, narrow, and documented so future developers do not accidentally broaden access. For single-page apps, route rules and navigation fallback must be planned together. For APIs, rules should protect paths without hiding backend health. The cleaner the route table, the easier production incidents are to reason about.

Security

Security impact is direct because route rules can allow or deny access to pages and API paths. Do not rely on hidden links, front-end checks, or obscurity to protect sensitive content. Use role requirements where appropriate, test anonymous access directly, and verify that API routes are not accidentally left public. Review redirects and rewrites so they do not create open-redirect patterns or leak protected paths. Security reviewers should inspect route rules in pull requests and test them in preview environments. A rule that looks harmless can become a serious exposure if it matches broader paths than intended. Test this path before approval and record the expected route-rule behavior.

Cost

Cost impact is indirect but real. Route rules do not create a separate billing object, yet bad routing can increase support time, failed API calls, logging volume, and downstream traffic. Redirect loops can generate noisy requests. Missing cache or rewrite discipline can send more traffic to APIs than intended. Publicly exposed routes may invite unwanted scraping or automated probing. The most expensive cost is often human: release delays while teams discover that a small config change broke navigation or access. Cost control comes from review, narrow rules, synthetic checks, and avoiding route behavior that creates unnecessary backend load. Test this path before approval and record the expected route-rule behavior.

Reliability

Reliability impact is direct because route rules control whether requests reach the right content. A bad rule can break deep links, create redirect loops, return wrong status codes, or route users away from working pages. Changes should be tested with direct browser navigation, refreshes, old URLs, protected pages, and /api calls. Rollback is usually a source-control deployment, so the last known good configuration should be easy to identify. Reliable route-rule management favors small changes, preview validation, and clear expected results. Operators should treat route-rule failures as configuration incidents, not just front-end bugs. Test this path before approval and record the expected route-rule behavior.

Performance

Performance impact is indirect for static file delivery and direct for request paths affected by redirects, rewrites, and API routing. A clean rule can send users quickly to the right page. A messy chain can add extra round trips, delay first interaction, or route browser requests through slower paths. Single-page app fallback behavior also affects perceived performance when users open bookmarked pages. Operators should test response codes, redirect counts, cache headers, and API timings after rule changes. Route rules should make the request path simpler, not create hidden latency that appears as a front-end performance problem. Test this path before approval and record the expected route-rule behavior.

Operations

Operators handle route rules by reviewing the deployed staticwebapp.config.json, reproducing failing paths, comparing preview and production environments, and checking authentication state. They should capture the exact URL, response code, redirect chain, user role, environment, and build version. Practical operations include testing anonymous and authenticated requests, confirming API path behavior, and reviewing recent pull requests that touched configuration. Because route rules are source-controlled, the fix often requires a repository change and deployment, not a portal edit. Runbooks should point engineers to the config file and the validation checklist. Test this path before approval and record the expected route-rule behavior.

Common mistakes

• Writing a broad wildcard rule that catches assets or API paths the team never intended to protect or redirect.
• Testing navigation clicks but not direct browser refreshes, bookmarked links, or unauthenticated requests.
• Assuming client-side route guards protect content when the Static Web Apps route rule remains public.
• Changing redirects during migration without checking for loops, incorrect status codes, or lost query strings.
• Forgetting that route-rule fixes require repository deployment, so portal-only troubleshooting cannot resolve the config problem.