Evaluate Builder for a Static Web Apps app
Use this guide to assess whether App Service Builder could be an alternative for your Azure Static Web Apps (SWA) application, then test a separate development/test copy.
At a glance
- Inventory the SWA features your app actually uses, including deployment and security requirements.
- Compare every required capability with current Builder feature availability.
- If a required capability is unsupported or unconfirmed, Builder is not yet a viable alternative for the complete app.
- Keep your existing SWA app in place while testing an isolated Builder app.
App Service Builder is in Private Preview for development and test workloads. This is an evaluation guide, not an official migration or production cutover procedure. Do not move production traffic, change your existing DNS, or delete your SWA resource. A successful trial does not approve a production migration or establish feature parity, an SLA, or future availability. Follow Private Preview guidance and use only the access, subscription, and location supplied by your preview contact.
1. Inventory your existing app
Review your repository, SWA resource configuration, deployment workflows, and application code. Do not judge compatibility from the frontend framework or a working home page alone.
| Where to look | What to record |
|---|---|
| SWA GitHub Actions or Azure DevOps workflow | Source repository, branch, app_location, api_location, output_location, build commands, build-time values, and deployment automation |
staticwebapp.config.json | Route rules, rewrites, redirects, navigationFallback, allowedRoles, response overrides, headers, MIME types, authentication, and networking settings |
| SWA resource and related Azure resources | Custom domains, staging environments, linked backends, private connectivity, identity, application settings, and separately owned services |
| Frontend and API code | Direct links, /.auth/* calls, identity/role assumptions, API paths, CORS, secrets, data access, and background/event-driven work |
| Your operational requirements | Geographic delivery, latency, availability, logs/metrics, deployment isolation, limits, costs, and data/security requirements |
Use the SWA configuration reference to interpret settings rather than copying them into a Builder manifest. Features can depend on your SWA plan and configuration; record what your app needs, not everything SWA offers.
For each requirement, keep a small assessment:
| Requirement | Used today? | Required? | Builder status and evidence | Trial result |
|---|---|---|---|---|
Example: direct navigation to /dashboard | Yes | Yes | Needs route/fallback verification | Not tested |
| Example: production custom domain | Yes | Yes | Not supported in this preview | Blocks suitability; service-provided URL is for the trial only |
Mark a requirement optional only if your application can genuinely operate without it. Do not remove access controls, weaken a firewall, or expose secrets to make the comparison pass.
2. Compare required capabilities
This table is an assessment aid, not a second feature roadmap. Recheck feature availability and the linked guides before each evaluation. Do not depend on features listed as not ready for use or planned.
| SWA capability or dependency | Builder preview assessment | What this means for your evaluation |
|---|---|---|
| Static HTML or a built frontend | Builder documents browser-ready static output and Vite builds. Other frameworks/toolchains require confirmation and a deployed test. | Use the static-site tutorial and runtime reference. Check the generated assets, not just whether a build succeeds. |
| SWA configuration and routing | builder.yaml describes components, build output, public mounts, startup, and health checks; it does not import staticwebapp.config.json or provide a compatible SWA rule engine. | Assess each rewrite, redirect, fallback, header, MIME type, and response override separately. A component path is not a SWA route rule. Required behavior without a supported, tested equivalent blocks suitability. |
| Built-in sign-in, custom providers, roles, or invitations | GitHub and managed Microsoft Entra work-account sign-in use configured provider applications. GitHub also supports your own OAuth application, and Entra supports your own registration through a user-assigned managed identity. Builder's access rules do not carry over SWA role assignments or invitations. | Review authentication. Test identity responses, sign-in/out, redirects, and allowed/denied users. Similar /.auth/* paths do not establish compatible response shapes, sessions, or authorization. Your app remains responsible for operation-level permissions. |
Managed Functions or a linked /api backend | Builder's web output is an HTTP process, not a managed Azure Functions runtime or an automatic SWA backend-linking feature. At most one static and one public web output can be deployed. | Assess API hosting separately. Porting Functions code to an HTTP app is application work, not a manifest conversion; event triggers and bindings do not become supported Builder features. A reachable external API remains separately owned and must enforce authentication and CORS where needed. See networking and connecting to services. |
| GitHub/Azure DevOps deployment workflows | Current Builder quickstarts use authorized GitHub source and builder.yaml. Native push deployment is not ready for use; GitHub Actions workflow integration is planned, not a published workflow. | Keep the SWA workflow intact. Use source control and an explicit Builder deployment for the trial. An existing SWA workflow or deployment token does not configure Builder access. |
| Pull-request staging environments | Builder preview environments are planned, not a supported equivalent to SWA pull-request staging. Retained versions are not parallel staging environments. | If automatic isolated PR environments are required, record a gap. A separately created test app is a manual evaluation surface, not feature parity. See deployments. |
| Custom domains | Builder custom domains are not supported in this preview. | Use the service-provided URL only for testing. If a custom domain is required for your app, the complete app is not suitable yet. See networking. |
| Globally distributed static delivery | SWA documents globally distributed static content. Builder's ability to serve static files does not establish equivalent geographic delivery or performance guarantees. | Record your geographic, latency, and availability requirements. Test representative access for evaluation, but do not treat a local speed check as a guarantee or production qualification. See the platform comparison. |
| Private networking or identity-based Azure access | Builder customer VNet/private-endpoint workflows are unsupported; apps use managed identity for Azure access. | If the Builder-hosted part requires private connectivity, suitability is blocked. A separately hosted backend keeps its own identity/networking; assess the connection to it independently. Do not make a private dependency public or replace required identity controls with weaker access. See networking and managed identity. |
| App settings, build values, and secrets | Builder variables are captured in a new version and shared across build components and web runtime. Static builds can expose values in browser assets; runtime-only secrets and managed secret references are not supported settings. | Separate public frontend configuration from sensitive backend values. Do not copy production secrets into the trial. Review variables before selecting a supported configuration approach. |
| Runtime diagnostics, scaling, and service limits | Builder provides build/deployment logs, configurable runtime-log export, and CPU, memory, or HTTP autoscaling. Image-backed apps can opt into scale to zero. | Compare requirements against diagnostics, scaling, and limits. Follow their prerequisites and keep a positive minimum for long-running requests or background work. |
Choose one outcome before deploying:
- Candidate for a trial: every required capability has a documented path, with any target-specific availability confirmed.
- Wait for support or confirmation: a required capability is unsupported, planned, under construction, or unconfirmed; Builder is not yet a viable alternative for the complete app.
- Test a limited component: a frontend-only experiment may still be useful, but excluded APIs or security requirements remain blockers for the complete app.
Even a candidate remains a development/test evaluation. See SWA's overview and authentication guidance for the source-side capabilities in this comparison.
3. Prepare an isolated Builder trial
Start only after obtaining preview access and confirming the capabilities needed for the selected trial. Use a separate Builder app, test data, and isolated dependencies appropriate for development/test use. Keep SWA serving the existing workload throughout.
- Create a separate evaluation branch or repository copy, retaining the SWA workflow and configuration. Ensure trial pushes cannot accidentally deploy changes to the live SWA app.
- Describe the selected build in
builder.yamlat the Builder app source root. Use the static-site tutorial as a known starting shape and the manifest guide to adapt your existing source; do not overwrite your app with a sample. - Set only trial configuration using application variables. Use test endpoints and credentials, and verify that sensitive values cannot enter static build output.
- Use the Create and deploy the app section of the static-site tutorial with your evaluation repository and branch, not a replacement sample. Choose Portal or the approved Builder CLI and authorize GitHub access separately. For a monorepo app root, follow source-control root selection through CLI or ARM.
- Track deployment to completion, confirm the active version/source revision, and open the returned service-provided app URL. An accepted request or successful build is not evidence that the app works.
Translate build settings deliberately:
| SWA setting or behavior | Builder configuration to review |
|---|---|
app_location | Select the app source root containing builder.yaml, then a component rootDirectory relative to that root. These are two different directory settings. |
output_location | Select static output according to output resolution. No-build output is source-relative; built output is resolved beneath the generated output root. |
| Custom frontend build | Use a supported platform and, when needed, a custom build that stages final files under $DESTINATION_DIR. Confirm the toolchain/version on your preview target. |
api_location or linked API | Make a separate API-hosting decision; there is no direct field translation. If evaluating a Builder web component at /api, implement its full public paths, including /api/health, without assuming the mount is stripped. |
staticwebapp.config.json | Keep it for SWA, but assess its behavior separately. Copying the file into Builder output does not configure routing or enforce its access rules. |
Generic static frontend plus HTTP backend is a documented Builder shape; verify your trial's runtime, public paths, assets, and API responses. Do not assume a static-site success also validates Functions, a linked backend, or a hybrid framework such as Next.js. Use a separate test API where needed; do not modify production dependency access merely to enable the experiment.
4. Test the behavior you depend on
Run the same application journeys against the existing SWA app and the isolated Builder URL, using appropriate test accounts and data. Record the Builder version/revision and the outcome for each requirement. Do not test destructive actions against production data.
| Test area | Checks to perform |
|---|---|
| Static files and client routing | Home page, JavaScript/CSS/images, nested URLs opened directly and refreshed, trailing slashes, missing files, fallback exclusions, and expected MIME types. Confirm a missing API or asset does not silently return the frontend HTML. |
| HTTP behavior | Required redirects and status codes, cache/security headers, methods, and error responses. Check actual responses rather than visual similarity alone. |
| Authentication and authorization | Sign-in/out, identity response fields used by your code, redirect destinations, an allowed user, a disallowed user, and an anonymous user. Verify protected API operations and files cannot be accessed directly; hiding a frontend control is not authorization. |
| APIs and dependencies | Full API paths, browser-origin/CORS behavior where applicable, request/response contracts, dependency authentication, and expected failure behavior. Use isolated test data. |
| Configuration safety | Correct test settings in the deployed version; no credentials in assets, browser responses, source, or logs. A variable-name listing does not prove the running app captured its new values. |
| Delivery and operations | Complete deployment, active revision, another explicit test deployment, build/deployment diagnostics, and representative access performance. Use a retained version only if available; it is not a staging slot or continuous monitor. |
If an app fails, use troubleshooting to separate source/build, startup, deployment, and application failures. Treat missing functionality or a failed required check as a gap, not a reason to weaken the requirement.
5. Record whether to keep evaluating
Summarize what worked, what required application changes, and which requirements remain unsupported, unconfirmed, or failed. A useful result is "viable for further development/test evaluation", not "ready to migrate production." If any required capability remains a gap, keep the app on SWA and revisit Builder when that capability is supported.
Share sanitized findings with your preview contact; exclude secrets, customer data, and unsanitized logs. Recheck feature availability as the preview evolves. Do not schedule a production cutover based on this trial.
When finished, delete only the separate trial app and dependencies you created using the client quickstart's cleanup guidance. Keep the existing SWA resource, deployment workflow, domains, and data intact. Cost explains the current preview offer and separately billed dependencies; a trial does not establish future pricing or cost equivalence with SWA.