PWABuilder Documentation

PWABuilder provides a suite of tools for creating and packaging Progressive Web Apps (PWAs). Key offerings include:

• PWABuilder.com: A web service to package PWAs for various app stores.
• PWA Studio: A VSCode extension that turns Visual Studio Code into a specialized development environment for PWAs.
• PWA Starter: A production-tested PWA template for starting new projects.
• <pwa-install>: A web component designed to provide an enhanced PWA installation experience.

PWABuilder consists of a frontend and a backend API.

• Frontend: Built using Lit web components, the WebAwesome web component library, Vite, and TypeScript.
• Backend API: Built using ASP.NET Core.
• Data Storage: The production backend uses Redis atomic lists for PWA analysis task queues and Azure Redis cache for storing analysis results.
• Local Development: When running locally, the system uses in-memory queues and cache, meaning a Redis instance is not required for local development.

The PWABuilder suite provides a set of tools designed to help developers create, develop, and package Progressive Web Apps (PWAs). The suite consists of three primary components:

1. PWA Starter: A production-tested, opinionated starter template for building new PWAs using a lightweight and extensible stack. It includes essential PWA features like a web manifest and service worker functionality via Workbox.
2. PWABuilder Studio: A Visual Studio Code extension that provides integrated tooling for PWA development, including template creation, manifest management, and store packaging.
3. PWABuilder: The core web-based tool (PWABuilder.com) used to generate store-ready packages for the Microsoft Store, Google Play Store, and iOS App Store, as well as side-loadable packages for testing.

The PWABuilder iOS platform is an experimental project that packages your PWA into an Xcode project using a Webkit-based web view (WKWebView). This allows you to publish your PWA to the iOS App Store.

Key features include:

• Service Worker Support: Enabled via App-Bound Domains on iOS 14 and above.
• App Shortcuts: Automatically supports app shortcuts defined in your web manifest.
• URL Capture: Supports opening app URLs directly in your PWA instead of a browser if an Apple App-Site Association file is deployed to your server.
• Mac Store Support: Option to opt-in for publishing to the Mac App Store for M1 devices running macOS 11 or later.

The service generates three types of packages for the Microsoft Store:

• Modern packages: Uses the Hosted App model on Windows May 2020 update or later. It uses Microsoft Edge as the host and is built using Edge's pwa_builder.exe tool.
• Classic packages: For Windows versions prior to the May 2020 Update. It uses the legacy EdgeHTML engine and is built using the MakeAppx.exe tool from the Windows SDK.
• Spartan packages: For the obsolete EdgeHTML-based Edge (Spartan). This is currently not used and may be removed.

The PWABuilder Report Card provides a visual analysis of your PWA via six distinct cards. It uses a color-coded progress ring system to indicate your development status:

• Red: Contains action items that prevent you from packaging your app for stores.
• Yellow: Required items are completed, but recommended items are missing.
• Green: All required and recommended items are completed.

The report card includes sections for App Preview, Store Packaging, Actionable Items (To-Do List), Manifest, Service Worker, and Security.

The PWA Studio extension provides a dashboard to ensure your application meets PWA requirements. The dashboard consists of three main sections:

• Web Manifest: Validates your manifest configuration.
• Service Worker: Validates your service worker implementation.
• Store Ready Checklist: A checklist to ensure your PWA is ready for app store publication.

If any section is missing required assets, the extension provides a button to automatically generate the necessary files (e.g., a button to generate a Service Worker).

PWABuilder Studio is a VS Code extension designed to provide a complete development environment for Progressive Web Apps (PWAs). It enables developers to:

• Create new PWAs: Start from a brand new project using the pwa-starter template.
• Convert existing apps: Transform a standard web application into a PWA by adding a web manifest, service workers, and generating required icons.
• Audit and Validate: Check if your PWA is installable and meets app store requirements.
• Package for Stores: Prepare and package your PWA for the Microsoft, Google, and Apple App Stores.
• Generate Assets: Automatically generate service workers for offline support and all correctly sized icons.
• Deploy: Publish your PWA to the web using Azure Static Web Apps.
• Enhance UX: Use built-in snippets to improve the user experience of your PWA.

The development workflow relies on the following tools:

• Vite: Handles code bundling and the development server. It includes the VitePWA plugin to expose PWA-specific functionality.
• Azure Static Web Apps CLI: Used for deploying the PWA to Azure and performing local performance testing.

The PWA Starter is built using a lightweight stack of web component-based libraries:

• Lit: Used to build custom web components. All pages in the starter are components built with Lit.
• Shoelace: Provides prebuilt UI components (buttons, modals, etc.) for the user interface.
• @thepassle/app-tools router: A lightweight client-side router designed to work with web components for application routing.

To ensure the best experience for Windows users, you should provide specific icon assets in your web manifest. While PWABuilder can automatically generate missing sizes by scaling a large, square PNG, providing your own assets allows you to change the content of the icon based on the available surface area (e.g., showing a simplified logo for small taskbar icons and a full logo for medium tiles).

Recommendation: Use higher levels of icon support (providing specific sizes for different tiles) to allow for context-aware icon content.

You can debug your PWA running in an iPhone simulator using Safari on a Mac:

1. Open your .xcworkspace file in Xcode.
2. Run the project (click ▶) to launch the PWA inside the iPhone simulator.
3. Open Safari on your Mac.
4. In the top menu bar, navigate to Develop -> Simulator [device name] -> [Your PWA's URL].
5. Safari Dev Tools will open, allowing you to execute JS, set breakpoints, and inspect elements.