PWABuilder
The simplest way to create progressive web apps across platforms and devices.
This repo is home to several projects in the PWABuilder family of tools.
Tools
Docs
Components
Recommended Development setup
You will need the following things properly installed on your computer.
You should also be familiar with TypeScript which we use for this project. This helps give you more guidance as you code from intellisense when using VSCode.
We recommend the following tools for your dev setup:
Additionally, when you open the project in VS Code, you'll be prompted to install recommended extensions.
Development
Set the NODE_BIN environment variable, .vscode/launch.json for VS code and apps\pwabuilder\Properties\launchSettings.json for Visual Studio:
- Windows:
C:/Program Files/nodejs/node.exe
- Mac:
/usr/local/bin/node
- Linux:
/usr/bin/node
Using VS Code (App and API)
- Run
VSCode Run and Debug (F5 key) to build the project and start a local Edge browser.
- Closing the Edge browser will terminate the debug session.
Using Visual Studio (API only)
- Open the solution and run the
https profile (F5 key)
Alternatively, build the Dockerfile.production container and access it from http://localhost:8080
Deployment
The web app, Microsoft Store, and Google Play deployment workflows publish uniquely tagged
images containing the commit SHA, workflow run ID, and run attempt. Each workflow
deploys the digest captured from its pushed image, not a mutable :production
or :latest tag. This prevents a subsequent preview build from changing the
image a deployed slot pulls on restart or scale-out.
Promote the tested image by swapping slots or deploying its exact digest.
Existing production slots using mutable tags must be pinned separately to their
verified known-good digests; changing these workflows does not update live slots.
Retain images referenced by deployed slots and images needed for rollback.
Breaking web app and Google Play API changes still require coordinated releases.
Pull request deployment slots
Pushes to main deploy changed services to their existing shared slots:
pwabuilder/preview, pwabuilder-windows-docker/staging, and
pwabuilder-cloudapk/staging. Manual packager workflow runs also use their shared
slots. The web app deploys to shared preview only on a push to main (including
PR merges); manual web workflow runs build an image but do not deploy it.
PRs targeting main from branches in this repository instead create or update
pr-<number> slots on the affected apps. Fork PRs are skipped before any build
or Azure login. The deployed slot URLs appear in workflow run summaries and
GitHub's staging environment deployment records. After deployment, a separate
job refreshes a PR deployments section of the PR description with successful
service links for that commit. Hidden pwabuilder-pr-deployments:start and
pwabuilder-pr-deployments:end markers delimit the managed section; text outside
those markers is preserved. Publishing jobs share a per-PR concurrency lock and
collect all successful service deployments so concurrent builds do not lose links.
Only publishing receives pull-requests: write; Azure deployment retains read
access. Failed, closed, superseded, and fork PR deployments do not publish links.
The three service workflows retain their own builds and call deploy-pr-slot.yml
for PR deployment. delete-pr-slots.yml handles both merged and unmerged closed
PRs, without path filters, and executes only the trusted default branch.
Cleanup checks all three apps and tolerates missing slots, but reports Azure
errors. Deploy and cleanup jobs share a per-app/PR concurrency lock and recheck
the current PR state; obsolete builds are skipped, late builds clean up closed
PRs, and cleanup skips reopened PRs. A reopened PR gets a fresh deployment.
If cleanup fails or is cancelled, rerun the cleanup workflow run.
Before enabling PR deployments, configure Azure and GitHub:
- Ensure each App Service plan has spare deployment slots and enough shared
compute capacity. Slots require Standard, Premium, or Isolated plans.
Standard supports five deployment slots per app, including existing staging
slots; reaching the limit fails deployment rather than replacing another slot.
- Grant the deployment identities permission to list apps, read source slot
configuration, and create, configure, restart, and delete slots on their
corresponding apps.
AZURE_WESTUS3_APP_ID handles the web app,
AZURE_EASTUS_APP_ID handles Microsoft Store, and AZURE_CENTRALUS_APP_ID
handles Google Play. The existing AZURE_WESTUS_APP_ID build identity still
pushes packager images to ACR. Subscription and tenant secrets are unchanged.
- Configure federated OIDC credentials for the contexts used by these workflows.
This repository uses customized subjects with stable owner/repository IDs:
builds without a GitHub environment use
repository_owner_id:11843769:repository_id:33142199:ref:refs/heads/main or
repository_owner_id:11843769:repository_id:33142199:pull_request;
PR deployments and cleanup use
repository_owner_id:11843769:repository_id:33142199:environment:staging.
The existing Azure identities already trust these required subjects.
The web deployment identity pwabuilder-managed-id-west-us-3 explicitly trusts
the staging-environment subject for PR deployment and cleanup; its existing
main and PR-build credentials are preserved.
Keep any GitHub staging environment protection rules compatible with PR
deployments and cleanup. Required approval rules also delay slot deletion.
- Source slots must have auto-swap disabled and working container registry
authentication. User-assigned identities are attached to PR slots without
creating new role assignments; the workflow identity needs permission to
assign them, and those identities need existing access to ACR and any runtime
dependencies. A source with both system- and user-assigned identities is
supported: PR slots use the existing user-assigned identity, not a new
system-assigned principal. The helper selects the configured ACR identity or
the single attached user identity, sets the PR slot's ACR client ID and
AZURE_CLIENT_ID, and fills an empty
AppSettings__AzureManagedIdentityApplicationId with that client ID.
It rejects system-only or ambiguous identity configurations. Existing source
slots retain their original identity selections.
- Each deployment identity has Managed Identity Operator scoped to its own
existing user-assigned identity and Network Contributor scoped to the
existing staging subnet, plus Reader scoped to the subnet's parent VNet.
Some Azure CLI versions read the parent VNet even when delegation checks are
skipped; Reader allows that lookup without granting VNet write permissions.
PR slots attach those identities and join those
subnets without changing subnet delegation or source slot configuration.
These grants do not authorize changing unrelated identities or networks.
Runtime data permissions (such as Cosmos DB data roles) are separate from
these deployment permissions and must cover the selected user identity.
Microsoft Store's has Cosmos DB Built-in Data
Contributor scoped to 's
container for PR package analytics.
The web PR slot retains the preview slot's packaging endpoints. It does not
automatically route to matching PR packager slots, and the existing Android
endpoint allowlist is unchanged. Packager PR slots can be tested directly.
Never swap a PR slot into production. Deleting a slot does not delete its ACR
images; apply an image retention policy that preserves deployed and rollback
digests.
Run the slot lifecycle regression checks with
pwsh -NoProfile -File .github/scripts/tests/test-pr-slot.ps1.
They simulate Azure and GitHub responses without changing cloud resources.
Run PR-description publishing tests with
node --test .github/scripts/tests/test-pr-deployment-links.cjs.
License
All files on the PWABuilder repository are subject to the MIT license. Please read the License file at the root of the project.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
