Deploy Angular micro frontends to Azure Static Web Apps
What you’ll achieve
Section titled “What you’ll achieve”You will deploy the OrdersPortal shell and the orders-mfe remote as two independent Azure Static Web Apps, each with its own GitHub Actions workflow and deployment token. The remote allows the shell’s origin through CORS, index.html and federation metadata are revalidated on every load while hashed files are cached for a year, and the remote’s pipeline refuses to deploy a build that breaks the shell’s contract. You will also see why a Static Web Apps deployment can break browser tabs that are already open, how to prevent that, how to roll back, and when Blob Storage with Azure Front Door is the better host.
Prerequisites
Section titled “Prerequisites”- The shell and remote from Host application setup and Remote configuration, tested as in Local testing.
- An Azure subscription where you can create Static Web Apps, and a GitHub repository (or one per app). Toolchain versions are listed in Prerequisites.
- Production hosts use invented names:
https://portal.example.testfor the shell andhttps://orders.example.testfor the remote.
Azure facts on this page were checked against Microsoft Learn on 2026-11-15. The JSON and YAML below are configuration, not runnable programs, and no Azure resources were created for this page. The build, contract-check and carry-forward commands were run locally against production builds made with Angular 22.2 and @angular-architects/native-federation 22.2.5.
The release model this tutorial uses
Section titled “The release model this tutorial uses”
Each remote is served from a stable root URL, and the shell’s manifest names that URL:
{ "orders-mfe": "https://orders.example.test/remoteEntry.json" }A normal remote release changes the files behind that URL; the manifest and the shell stay as they are. A rollback is a redeployment of the previous remote build. This is the simplest model that Static Web Apps supports well, and it is the one used on every page of this section. The alternative, immutable versioned paths with a separately hosted manifest, needs storage that keeps old files; it is described at the end of this page under Versioned releases on Blob Storage and Front Door.
Each deployable application gets its own Static Web App:
| Static Web App | Serves | Deployed by | Custom domain |
|---|---|---|---|
orders-portal |
dist/orders-portal/browser plus the environment’s manifest |
Platform team’s workflow | portal.example.test |
orders-mfe |
dist/orders-mfe/browser |
Orders team’s workflow | orders.example.test |
The orders team deploys without touching the shell’s resource, token or pipeline. Static Web Apps also gives each app preview environments for pull requests, which you can point a preview shell at.
Check the quotas against your plan before you commit to this layout. Microsoft Learn lists, among others: 10 apps per subscription on the Free plan and 100 on Standard; 3 preview environments per app on Free and 10 on Standard; 250 MB of storage per environment on Free and 500 MB on Standard; 15,000 files per app; and 2 custom domains on Free versus 6 on Standard. Networking features such as IP restrictions and private endpoints need the Standard plan.
Step 1: Add staticwebapp.config.json to the remote
Section titled “Step 1: Add staticwebapp.config.json to the remote”Microsoft Learn recommends placing staticwebapp.config.json in the folder set as app_location; when a build step produces the output, the file must end up at the root of that output. Put it in the remote’s public/ folder so the Angular build copies it into dist/orders-mfe/browser/, which is the folder the workflow deploys:
{ "globalHeaders": { "Access-Control-Allow-Origin": "https://portal.example.test", "Vary": "Origin", "Cache-Control": "no-cache" }, "routes": [ { "route": "/*.{js,css}", "headers": { "Cache-Control": "public, max-age=31536000, immutable" } } ], "navigationFallback": { "rewrite": "/index.html", "exclude": ["/*.{js,css,json,map,ico}"] }}This page is the one place in the section that states the caching rule, so here it is in full:
- Everything revalidates by default.
globalHeadersapplies to every response unless a route rule overrides the same header (Microsoft Learn’s configuration reference). That covers/index.htmlwhether it is requested directly or served by the navigation fallback, plusremoteEntry.json,importmap.jsonandfavicon.ico. These names stay the same across releases, so a browser must ask the server whether they changed. - Hashed files are immutable. Every
.jsand.cssfile in a production build has a content hash in its name:routes-SOX43SHM.js,order-detail-G5LQHHY2.js,_angular_core.Wz6rTecDmZ.js. The route rule overridesCache-Controlfor them with a one-year lifetime. - CORS names the exact origin. The shell fetches the remote’s metadata and modules cross-origin, so the remote must allow the shell’s origin. Microsoft Learn shows
globalHeadersas the place for a custom CORS configuration. Avoid*; if several shells or environments load the remote, template the value per environment in the workflow. - The fallback excludes assets. The fallback lets deep links in the remote’s standalone mode work. Without the exclusion, a request for a missing
remoteEntry.jsonor chunk would be answered withindex.htmland status 200, which the federation runtime reports only as a generic load failure. With it, a missing file is a clean 404.
Route rules are evaluated in order and stop at the first match. Microsoft Learn documents wildcards only at the end of a path and extension filters in braces, and limits the file to 20 KB.
Verify: npx ng build orders-mfe and ls dist/orders-mfe/browser/staticwebapp.config.json shows the file in the build output.
Step 2: Add staticwebapp.config.json to the shell
Section titled “Step 2: Add staticwebapp.config.json to the shell”The shell gets the same caching rules, a Content Security Policy that allows exactly the remote origins in its manifest, and no CORS header (nobody loads the shell cross-origin):
{ "globalHeaders": { "Cache-Control": "no-cache", "Content-Security-Policy": "default-src 'self'; script-src 'self' https://orders.example.test blob:; connect-src 'self' https://orders.example.test https://api.example.test; style-src 'self' 'unsafe-inline'" }, "routes": [ { "route": "/*.{js,css}", "headers": { "Cache-Control": "public, max-age=31536000, immutable" } } ], "navigationFallback": { "rewrite": "/index.html", "exclude": ["/*.{js,css,json,map,ico}"] }}federation.manifest.json and /index.html fall under the global no-cache, so a redeployed manifest takes effect on the next page load. Why each CSP source is needed, and what breaks without it, is shown in Advanced concepts. Every time you add a remote to the manifest, add its origin here in the same pull request.
This policy has no 'unsafe-inline' in script-src, so the shell’s index.html must not contain inline scripts. A production build adds one as soon as the shell has global styles: critical-CSS inlining writes <link rel="stylesheet" href="#styles-<hash>.css" media="print" data-beasties-media="all"> plus a small inline <script> that switches the link to all. In our rehearsal, one rule in the shell’s styles.css was enough for Chrome to block that script (Executing inline script violates the following Content Security Policy directive 'script-src 'self' http://localhost:4201 blob:'), and the global stylesheet stayed media="print", unapplied. Turn critical-CSS inlining off for the shell. After the federation schematic, the original build options live in the esbuild target, so set this in angular.json under projects.orders-portal.architect.esbuild.configurations.production:
"optimization": { "styles": { "inlineCritical": false } }The rebuilt index.html then has a plain <link rel="stylesheet" href="#styles-<hash>.css">, no executable inline script (the <script type="esms-options"> block that remains is JSON configuration for es-module-shims, which never executes, so CSP does not block it), and the same policy rendered the pages with the global styles applied. Script and font optimization keep their default true. The alternative is to allow the script’s hash ('sha256-…', which Chrome prints in the error) in script-src, but that hash changes whenever the critical-CSS tool’s output changes, so you would have to recheck it after every Angular upgrade.
Verify: after deployment, curl -sI https://portal.example.test/orders shows cache-control: no-cache and the content-security-policy header.
Step 3: Create the two Static Web Apps
Section titled “Step 3: Create the two Static Web Apps”In the Azure portal, create a Static Web App for each application and select Other as the source under Deployment details, because the workflow below builds and uploads the app itself (Microsoft Learn describes this flow for external CI providers). Copy each app’s deployment token from Overview > Manage deployment token, or with the Azure CLI:
az staticwebapp secrets list --name orders-mfe --query "properties.apiKey"Store each token as a GitHub Actions secret in the repository that deploys that app, for example AZURE_STATIC_WEB_APPS_API_TOKEN_ORDERS_MFE. Microsoft Learn’s wording is “Don’t store the deployment token in a public repository”; in practice keep it out of every repository and only in the secret store. If a token leaks, reset it under Manage deployment token and update the secret.
Verify: each app’s Overview page shows its default *.azurestaticapps.net URL, and the secret exists in the repository settings.
Step 4: The remote’s workflow: check the contract, carry forward, deploy
Section titled “Step 4: The remote’s workflow: check the contract, carry forward, deploy”The remote’s pipeline is where a breaking change must be stopped, because the remote is the side that changes. The workflow builds, checks the build against what the shell expects, carries the previous release’s hashed files forward, and deploys with skip_app_build: true:
name: Deploy orders-mfe
on: push: branches: [main] paths: - 'projects/orders-mfe/**' - 'package-lock.json' - 'tools/check-contract.mjs' - '.github/workflows/deploy-orders-mfe.yml' workflow_dispatch: inputs: ref: description: 'Tag, branch or commit to deploy (for a rollback, the last good release)' required: true default: main
# One deployment at a time; a queued run waits instead of canceling a running upload.concurrency: group: deploy-orders-mfe cancel-in-progress: false
jobs: build_and_deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 with: ref: ${{ inputs.ref || github.sha }} - uses: actions/setup-node@v7 with: node-version: 24 cache: npm - run: npm ci - run: npx ng build orders-mfe
# Consumer-driven contract: the shell's expectations, owned by the platform team. - run: node tools/check-contract.mjs dist/orders-mfe/browser/remoteEntry.json ./routes 22.2
# Keep the previous release's hashed files so open tabs can still load them. # The newest saved cache is whatever is live now, even when this run deploys an older ref. - uses: actions/cache/restore@v6 with: path: previous-release key: orders-mfe-release-${{ github.run_id }}-${{ github.run_attempt }} restore-keys: orders-mfe-release- - name: Carry previous release forward run: | if [ -d previous-release ]; then mv previous-release carried; fi cp -r dist/orders-mfe/browser previous-release if [ -d carried ]; then cp --update=none carried/*.js dist/orders-mfe/browser/; fi
- name: Deploy uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ORDERS_MFE }} action: upload app_location: dist/orders-mfe/browser output_location: '' skip_app_build: true
- uses: actions/cache/save@v6 with: path: previous-release key: orders-mfe-release-${{ github.run_id }}-${{ github.run_attempt }}The paths filter is the monorepo pattern from Microsoft Learn’s build configuration article: only changes that affect the remote trigger its deployment. In a repository per app you can drop it. The cache key is unique per run and the restore uses only the prefix, so every run carries forward the files of the release that is live at that moment. That matters for a rollback: a manual run for an older tag still keeps the files of the release it replaces, which is what the open tabs are using. concurrency keeps two deployments from overlapping. Action majors were checked against the action repositories’ tags on 2026-11-16 (actions/checkout v7, actions/setup-node v7, actions/cache v6, which still ships the restore and save actions).
The contract check
Section titled “The contract check”tools/check-contract.mjs reads a remoteEntry.json from a file or a URL and fails if an exposed key is missing or a shared Angular package is not a strict singleton on the agreed minor. The arguments (./routes and 22.2) are the shell’s expectations; the platform team owns them, and changing them is a reviewed change to the remote’s workflow. Save it as an ES module and run it with Node.js 22 or later:
// tools/check-contract.mjs: fail a pipeline when a remote build no longer meets the shell's contract.// Usage: node check-contract.mjs <URL or path of remoteEntry.json> <exposed keys, comma separated> <Angular major.minor>import { readFile } from 'node:fs/promises';
const [source, keysArg, angularMinor] = process.argv.slice(2);const text = /^https?:\/\//.test(source) ? await fetch(source).then((r) => { if (!r.ok) throw new Error(`${source}: HTTP ${r.status}`); return r.text(); }) : await readFile(source, 'utf8');const entry = JSON.parse(text);
const problems = [];const exposed = entry.exposes.map((e) => e.key);for (const key of keysArg.split(',')) { if (!exposed.includes(key)) problems.push(`missing exposed key ${key}`);}for (const name of ['@angular/core', '@angular/common', '@angular/router']) { const pkg = entry.shared.find((s) => s.packageName === name); if (!pkg) problems.push(`${name} is not shared`); else if (!pkg.singleton || !pkg.strictVersion) problems.push(`${name} is not a strict singleton`); else if (!pkg.version.startsWith(`${angularMinor}.`)) { problems.push(`${name} ${pkg.version} is not on the agreed minor ${angularMinor}`); }}
if (problems.length > 0) { console.error(`${entry.name}: contract check FAILED\n- ${problems.join('\n- ')}`); process.exit(1);}const core = entry.shared.find((s) => s.packageName === '@angular/core');console.log(`${entry.name}: exposes ${exposed.join(', ')}; @angular/core ${core.version}; contract OK`);Run against the real 22.2 production build, against the same build with expectations it does not meet, and against the remoteEntry.json of the same remote built with Angular 22.1.8 and adapter 22.1.3:
$ node tools/check-contract.mjs dist/orders-mfe/browser/remoteEntry.json ./routes 22.2orders-mfe: exposes ./routes; @angular/core 22.2.6; contract OK
$ node tools/check-contract.mjs dist/orders-mfe/browser/remoteEntry.json ./routes,./summary-widget 22.3orders-mfe: contract check FAILED- missing exposed key ./summary-widget- @angular/core 22.2.6 is not on the agreed minor 22.3- @angular/common 22.2.6 is not on the agreed minor 22.3- @angular/router 22.2.6 is not on the agreed minor 22.3
$ node tools/check-contract.mjs orders-mfe-22.1/remoteEntry.json ./routes 22.2orders-mfe: contract check FAILED- @angular/core 22.1.8 is not on the agreed minor 22.2- @angular/common 22.1.8 is not on the agreed minor 22.2- @angular/router 22.1.8 is not on the agreed minor 22.2The check exits with status 1 on failure, which stops the workflow before deployment. The same script works with a URL (https://orders.example.test/remoteEntry.json), so the shell’s pipeline can run it as a smoke test after each environment change. What happens in the browser when a 22.1 remote reaches a 22.2 shell anyway is shown in Advanced concepts.
Why carry the previous release forward
Section titled “Why carry the previous release forward”Each deployment uploads the complete contents of app_location. Microsoft Learn’s FAQ states that when a deployment completes, all requests are served the latest version of your files, and Learn documents no option to keep files from an earlier deployment. Treat every deployment as a full replacement: hashed files that are not in the new upload are gone.
That breaks tabs that are already open. A tab that loaded the shell before the deployment holds the old remoteEntry.json in memory and keeps asking for the old hashed names. In a local rehearsal (production builds, a static server that replaced the remote’s whole folder exactly as a deployment does), the tab had the order list open; after the deployment, clicking an order produced:
[http 404] /order-detail-G5LQHHY2.jsERROR TypeError: 404 Not Found http://localhost:4201/order-detail-G5LQHHY2.jsNothing changed on screen: the navigation failed and the list stayed. With the carry-forward step (previous release’s .js files copied into the new upload without overwriting anything), the same click rendered the old detail page, and the next reload showed the new release. The step above copies only .js files, never remoteEntry.json or index.html, and saves the pure new build for the next run, so at most two releases’ scripts are deployed. In the rehearsal that was 46 files instead of 38, far inside the 15,000-file quota. The cache is best effort (GitHub evicts caches that are not used for a while), so pair it with the client-side mitigation in Host application setup, which reloads the page once when a lazy file cannot be fetched.
Verify: after two deployments, curl -sI https://orders.example.test/<a .js name from the previous remoteEntry.json> returns 200.
Step 5: The shell’s workflow
Section titled “Step 5: The shell’s workflow”The shell’s workflow is the same shape with orders-portal in place of orders-mfe, without the contract step, and with one step that installs the environment’s manifest before deployment:
- run: npx ng build orders-portal - run: cp deploy/manifests/prod.json dist/orders-portal/browser/federation.manifest.jsonThe shell’s build is environment-neutral; only the copied manifest differs. Changing a manifest means rerunning this workflow with the same build inputs, not changing shell code.
Verify: after both workflows succeed, curl -sI https://orders.example.test/remoteEntry.json shows cache-control: no-cache and access-control-allow-origin: https://portal.example.test, and https://portal.example.test/orders renders the orders area.
Step 6: Release, roll back, change a contract
Section titled “Step 6: Release, roll back, change a contract”- Remote release. The orders team merges to
main; its workflow checks the contract and deploys. BecauseremoteEntry.jsonrevalidates, the next page load in any browser uses the new build, and open tabs keep working thanks to the carried-forward files. The shell is not redeployed. - Rollback. Run the remote’s workflow manually (Actions > Deploy orders-mfe > Run workflow, or
gh workflow run deploy-orders-mfe.yml -f ref=<last good tag>) with the last good tag or commit asref. It rebuilds that code, runs the contract check, carries the live release’s files forward and deploys. Builds are reproducible for identical inputs: rebuilding the same remote source locally produced the same file names and a byte-identicalremoteEntry.json. Tag each production release so the last goodrefis easy to find. - Contract change (expand, then contract). When a change spans shell and remote, never deploy both at once. Expand first: the remote deploys a build that exposes both the old and the new contract (for example
./routesand./routes-v2), and the contract check is updated to require both. Then the shell deploys and switches to the new key. Only after the shell’s release is complete, and after the longest realistic session has expired, does the remote remove the old key and the check stops requiring it. Each step is independently deployable and independently reversible. - Angular upgrades are the exception to independent releases; see Advanced concepts.
Step 7: Static Web Apps authentication is not authorization for remotes
Section titled “Step 7: Static Web Apps authentication is not authorization for remotes”Static Web Apps allowedRoles rules secure only HTTP requests the platform serves; Microsoft Learn’s configuration reference notes that client-side route changes issue no request, so they are not secured, and the APIs the remote calls must validate the token and permission on every request. Where sign-in and sessions belong in a federated frontend is covered once, in Advanced concepts.
Versioned releases on Blob Storage and Front Door
Section titled “Versioned releases on Blob Storage and Front Door”If you need instant, pinned rollbacks (the shell chooses which remote build runs, and rolling back is a manifest edit), you need storage that keeps every release. Static Web Apps does not; a Blob Storage static website plus Azure Front Door does:
- Upload each remote build to its own prefix in the remote’s storage account, for example
$web/orders-mfe/2026.11.15-2/, and never overwrite a prefix. A lifecycle rule or a cleanup job deletes prefixes older than your longest session plus your rollback window. - Serve the manifest from a separately deployed configuration location, for example a
configcontainer routed by Front Door athttps://portal.example.test/config/federation.manifest.json, withno-cache. The shell callsinitFederation('/config/federation.manifest.json', ...), so the shell build does not change between environments. - Release and roll back by editing that one file, through a reviewed pull request and a small pipeline that uploads it. Old tabs are safe automatically, because nothing they reference is deleted.
Microsoft Learn lists the static website limits that make Front Door (or Azure CDN) necessary here:
- No CORS on the static website endpoint. Storage CORS rules do not apply to it, so a shell on another origin cannot load a remote from it directly.
- No custom headers. There is no way to configure headers in the static website feature itself; Learn points to Azure CDN rules for adding headers and caching rules.
- No authentication or authorization in the static website feature.
- HTTPS on a custom domain needs Azure CDN; Azure Storage does not support it natively.
Put Azure Front Door in front of the storage accounts and add the CORS, caching and CSP headers in its rule sets. Front Door can also route portal.example.test/ to the shell’s container and portal.example.test/orders-mfe/ to the remote’s, which puts both on one origin and removes the need for CORS. The cost is more infrastructure to own: storage accounts, a Front Door profile, rule sets, cleanup and a manifest pipeline.
Complete working result
Section titled “Complete working result”Two Static Web Apps, two workflows and two tokens. The remote’s output contains staticwebapp.config.json with CORS, revalidation by default, immutable hashed files and an asset-excluding fallback; its pipeline blocks contract breaks and carries the previous release’s scripts forward. The shell’s output contains the environment’s federation.manifest.json and a CSP that names the remote. Each team deploys alone, and the shell picks up a new remote on the next page load.
Troubleshooting
Section titled “Troubleshooting”- The shell shows the fallback, and the console reports a CORS error. The remote’s
Access-Control-Allow-Origindoes not match the shell’s exact origin (scheme, host and port). Check the deployedstaticwebapp.config.jsonand the response headers withcurl -sI. - Users report that clicking does nothing after a remote deployment; the console shows
TypeError: 404 Not Found .../order-detail-<hash>.js. An open tab asked for a file the deployment removed. Check that the carry-forward step ran (its cache may have been evicted) and that the shell has the reload-once handler. - Global styles are missing in production and the console reports
Executing inline script violates ... script-src. Critical-CSS inlining added an inline script; setinlineCritical: falsefor the shell as in Step 2. - The console reports a CSP violation for
blob:or for the remote’s origin. The shell’sContent-Security-Policydoes not listblob:inscript-srcor the remote’s origin inscript-srcandconnect-src. See Advanced concepts. - The contract step fails with “is not on the agreed minor”. The remote was built with a different Angular minor than the shell. Do not override the check; follow the upgrade choreography.
/orders/ord-1002returns a 404 page on refresh. The shell’snavigationFallbackis missing orstaticwebapp.config.jsonis not at the root of the deployed folder. Confirm it is inpublic/.- The deploy action builds the app again or cannot find the output. Set
skip_app_build: true, pointapp_locationat the built folder and setoutput_locationto an empty string. - The deploy step fails with an authorization error. The token secret belongs to a different Static Web App or was reset. Copy the current token into the secret.
Next steps
Section titled “Next steps”Read Advanced concepts for version skew, Angular upgrades, security headers and production error handling.
Related pages
Section titled “Related pages”- Host application setup
- Local testing
- Advanced concepts
- Create an Azure Static Web App
- Azure Static Web Apps custom domains
- GitHub Actions
Official references
Section titled “Official references”- Microsoft Learn: Configure Azure Static Web Apps (
staticwebapp.config.json, global headers, fallback routes) - Microsoft Learn: Build configuration for Azure Static Web Apps
- Microsoft Learn: Azure Static Web Apps FAQ (cache invalidation after deployment)
- Microsoft Learn: Quotas in Azure Static Web Apps
- Microsoft Learn: Deploy to Static Web Apps from external providers (source: Other)
- Microsoft Learn: Reset deployment tokens
- Microsoft Learn: Static website hosting in Azure Storage
- Microsoft Learn: Use Azure Front Door with Azure Storage blobs
- GitHub:
actions/cache(including therestoreandsaveactions) - Angular v22: Deployment
- Angular v22: Workspace configuration, optimization options (
inlineCritical)