Deploying modern Single Page Applications to Azure Static Web Apps

I had a need to deploy a single page application to Azure Static Web Apps. At first I thought I wouldn't have to write this note as it's already 2025 (as of writing) — I expected Azure to have caught up to the polish of Vercel and Netlify. But here we are.

What I liked

• Generous free tier — Their Free and Standard plans are separate but switchable. On the Free plan you never get charged; they just stop serving your app when you hit limits (whereas Netlify and Vercel might bill-shock you [1] [2])
• Streamlined GitHub Actions setup — I just connect my GitHub Account, and Azure portal auto-generates the workflow file for me. No need to copy and paste workflow files out of documentation.
• Latest LTS Node.js support — Works with Node.js 22 out of the box.

Hurdles to overcome

PNPM support

Nowadays, many developers have switched from npm and Yarn to pnpm. Unfortunately, Oryx, the build tool used by Azure Static Web Apps, still does not support pnpm or Corepack even in 2025.

I had to dig into its source code and documentation to find a workaround. The solution for now is to set environment variables to configure Oryx:

env:
  CUSTOM_BUILD_COMMAND: 'corepack enable && pnpm install && pnpm run build'

Single Page Application routing

SPAs need all routes to fallback to index.html to avoid 404s on page refresh, but this is not the default on Azure Static Web Apps. I had manually configure a fallback route by creating a staticwebapp.config.json file in my project root:

{
  "navigationFallback": {
    "rewrite": "/index.html"
  }
}