# PWABuilder is three tools, two sites and an empty root manifest > The PWABuilder repository is a container rather than a single application: the web app that packages progressive web apps for stores, the PWA Studio extension for Visual Studio Code, and links out to a starter template that lives in its own repository. Its root package.json is an empty object, its Dockerfile exposes one port and sets another, and its deployment description is a study in refusing mutable image tags. **pwa-builder/PWABuilder** — The simplest way to create progressive web apps across platforms and devices. Start here. This repo is home to several projects in the PWABuilder family of tools. - Repository: https://github.com/pwa-builder/PWABuilder - Website: https://docs.pwabuilder.com - Stars: 3,784 · Forks: 410 - Language: TypeScript - License: NOASSERTION - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/pwa-builder-pwabuilder ## The repository is a container for a family of tools The README says so in the second paragraph: this repo is home to several projects in the PWABuilder family of tools. That framing matters because the name is also the name of one of those projects. The tools table has three rows, each with an overview, a source path inside this repository, a documentation link and a contribution link. PWABuilder.com is described as the best way to package progressive web apps for various stores, and its source is the apps/pwabuilder directory. PWA Studio is described as making Visual Studio Code a development environment for building progressive web apps, with its source at apps/pwabuilder-vscode and a separate marketplace entry for the extension. PWA Starter is described as an opinionated and production tested template for new projects, and here the source column points outside this repository, at a separate pwa-starter repository, which is the first sign that the family spans more than one codebase. ## Two of the three deliverables do not live in this repository The tables quietly separate what is here from what is elsewhere. The starter template is in its own repository, linked as the source for PWA Starter, so a developer starting a new project clones a different repository entirely. The component table does the same thing: the pwa-install web component, described as being for a good progressive web app install experience, has its source, its documentation and its contribution link all pointing at a repository belonging to a different author. So of the four things named in the README, one is the web app, one is the editor extension, one is the template elsewhere and one is a component elsewhere. The documentation itself is also split in two: the documentation site is built from the docs directory of this repository, while the blog is served from a separate application directory, with its own source link rather than a wiki. ## The root package.json is an empty object Most monorepos put their workspace configuration in the root manifest. This one does not: the root package.json contains nothing but an empty pair of braces. What replaces it is the file layout. There is an apps directory holding the web app and the editor extension, a libraries directory, a components directory, a docs directory and a scripts directory. TypeScript configuration is shared through tsconfig.base.json rather than a root manifest, and dependency installation is handled by a package-lock.json that sits beside the empty manifest, which means each application installs for itself. There is also a solution file, PWABuilder.sln, alongside a .nuget directory, which is the hint that the API half of the project is a .NET application living in the same tree as the TypeScript front end. ## NODE_BIN is set by hand, per platform, or debugging never attaches The development section is dominated by one environment variable. To run the project in an editor you have to set NODE_BIN, and the value is given for three platforms: C:/Program Files/nodejs/node.exe on Windows, /usr/local/bin/node on Mac, and /usr/bin/node on Linux. The variable has to be set in two places, the launch configuration in .vscode/launch.json when using Visual Studio Code, and the launch settings file under the pwabuilder application's Properties folder when using Visual Studio. The reason is the next line: pressing F5 in Visual Studio Code builds the project and starts a local Edge browser, and closing that Edge window terminates the debug session. So the debug session lives as long as the browser window, and an unset NODE_BIN shows up as a build that runs but never opens the app. ## Visual Studio runs the API only, and Docker is the third route Three ways to run the project are described, and they are not equivalent. Visual Studio Code covers the app and the API together, with F5 building both and launching the browser. Visual Studio covers the API alone, where the instruction is to open the solution and run the https profile with F5. The third route is a container: build Dockerfile.production and reach the result at localhost on port 8080. The prerequisite list explains why there are three routes rather than one, since a developer needs Node.js, NPM, the .NET 9.0 SDK and Docker Desktop installed, plus familiarity with TypeScript since the project is written in it. Recommended tooling is Visual Studio Code as the editor and either Windows Terminal or hyper as the terminal, and the project also prompts for recommended extensions on first open. ## The Dockerfile exposes 3000 and sets the port to 80 The container recipe is nine lines and contains two mismatches worth knowing before anyone uses it as a template. It starts from a node 14 base image, which is well behind the .NET 9 SDK the development prerequisites ask for, so this file cannot be the image that runs the full solution. It declares EXPOSE 3000 and then sets an environment variable named PORT to 80, so the documented port and the runtime port disagree. The rest is mechanical: the working directory is /app, the repository is copied in wholesale, the working directory moves to the pwabuilder application, dependencies are installed with npm and the unsafe permission flag, and the start script is the command. Two other Dockerfiles sit beside it at the root, one for Windows with Chromium and one named production, which is the one the development section points at. ## Deployment pins image digests and rejects mutable tags on purpose The deployment section is the most specific prose in the README and it explains a deliberate design. The web app preview and Google Play staging workflows publish uniquely tagged images carrying the commit SHA, the workflow run ID and the run attempt, and each workflow deploys the digest captured from its pushed image rather than a mutable production or latest tag. The stated reason is that a later preview build would otherwise change the image a deployed slot pulls on restart or scale-out. Promotion is therefore done by swapping slots or deploying the exact digest, and the text is careful about the limit of that change: existing production slots using mutable tags must be pinned separately to their verified digests, and editing the workflows does not update live slots. It also states what the discipline does not solve, since images referenced by deployed slots and images kept for rollback must be retained, and breaking web app and Google Play API changes still require a coordinated release. ## Release tags are irregular and the licence has two answers The versioning signals are the weakest part of the repository's presentation. The recent releases are a tag named feb-2024 with the title February 2024 dated 2024-02-13, a tag named latest whose title is Staging Build dated 2024-01-25, and a tag named 1.0.4 dated 2015-05-06. So there is a staging tag with a mutable name, a date-named tag, and a numeric tag that predates both by nearly a decade. The last push to the default branch main is dated 2026-10-02 and the repository is not archived. Licensing has a similar split: the README states that all files on the repository are subject to the MIT licence and points to the licence file at the root, LICENSE.txt is present in the tree, and the repository metadata reports no machine readable licence identifier. The project also adopts the Microsoft Open Source Code of Conduct. ## Conclusion This repository suits a developer working on PWABuilder itself, or one who wants the three entry points in one place before choosing where to start. It does not suit someone looking for a single installable tool, since the packaging service, the editor extension and the starter template are three separate deliverables with three separate sources. Before you build, read the deployment paragraph carefully if you maintain the pipelines, because the digests it describes only protect new slots, and set NODE_BIN per platform or the debug session will not attach to the browser at all. ## FAQ ### What is PWABuilder? A family of tools described as the simplest way to create progressive web apps across platforms and devices. This repository holds the PWABuilder.com web app for packaging PWAs for various stores and the PWA Studio Visual Studio Code extension, and it links to a starter template and an install component that live in other repositories. ### How do I use PWABuilder? The README carries no usage steps and points to the documentation site at docs.pwabuilder.com plus a wiki for each tool. What it does document is development: install Node.js, NPM, the .NET 9.0 SDK and Docker Desktop, set the NODE_BIN variable for your platform, then start the app with F5 in Visual Studio Code. ### Is PWABuilder free to use? The README states that all files on the repository are subject to the MIT licence and points to the licence file at the root, which is LICENSE.txt. The repository metadata itself reports no machine readable licence identifier, so the terms are stated in prose rather than in a field tooling can read. ### What does PWABuilder offer for Visual Studio Code? PWA Studio, an extension published in the Visual Studio marketplace as PWABuilder.pwa-studio and described as making Visual Studio Code a development environment for building progressive web apps. Its source is the apps/pwabuilder-vscode directory of this repository, and its quick start is in the studio section of the documentation site. ## Sources - [Issues](https://github.com/pwa-builder/PWABuilder/issues) - [Project website](https://docs.pwabuilder.com) - [pwa-builder/PWABuilder on GitHub](https://github.com/pwa-builder/PWABuilder) - [README](https://github.com/pwa-builder/PWABuilder/blob/main/README.md) - [Releases](https://github.com/pwa-builder/PWABuilder/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pwa-builder-pwabuilder