Get started with Progressive Web Apps

Progressive Web Apps (PWAs) are websites that are progressively enhanced. The progressive enhancements include app-like features, such as installation, offline support, and push notifications.

You can also package your PWA for app stores, such as Microsoft Store, Google Play, and Mac App Store. The Microsoft Store is the commercial app store that's built into Windows 10 and later.

In this overview of PWA basics, you create a simple website and extend it as a PWA. The finished project works across modern browsers.

Tip

You can use PWABuilder to create a new PWA, enhance your existing PWA, or package your PWA for app stores.

To install or run a PWA on Windows, see Installing a PWA in The user experience of PWAs.

Prerequisites

Creating a basic website

In this step, you will create a simple HTML page to create a basic website, and will start a local web server to access the website in your browser.

  1. Create a new directory called MySamplePWA on your computer.

  2. Open Visual Studio Code, select File > Open Folder and then select the MySamplePWA directory to open your new project.

  3. Create a new file in the project by pressing Ctrl+N, add the following content, and save the file as index.html:

    <!DOCTYPE html>
    <html lang="en-US" dir="ltr">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width,initial-scale=1" />
        <link rel="shortcut icon" href="https://c.s-microsoft.com/favicon.ico?v2" />
        <title>My Sample PWA</title>
      </head>
      <body>
        <h1>My Sample PWA</h1>
      </body>
    </html>
    
  4. Start a local web server by using the http-server Node.js library:

    cd path\to\MySamplePWA
    npx http-server
    

    In the above commands, replace path\to\MySamplePWA with the actual path where you create the MySamplePWA folder.

You now have a simple, functional website running on a local web server.

Now browse to http://localhost:8080 to view your new website.

Running your new PWA on localhost.

Getting started building a PWA

Now that you have a simple website, extend it as a Progressive Web App (PWA) by adding the three requirements for PWAs:

Step 1 - Use HTTPS

Key parts of the Progressive Web Apps platform, such as Service Workers, require using HTTPS. When your PWA goes live, you must publish it to an HTTPS URL. Many hosts now offer HTTPS by default, but if your host doesn't, Let's Encrypt offers a free alternative for creating the necessary certificates.

For example, you can create an Azure free account. If you host your website on the Microsoft Azure App Service, it's served over HTTPS by default.

You can also host your website on GitHub Pages which supports HTTPS too.

For debugging purposes, Microsoft Edge also permits a localhost web server to use the PWA APIs without HTTPS. In this tutorial, you use http://localhost:8080 to build your PWA.

Step 2 - Create a Web App Manifest

A Web App Manifest is a JSON file containing metadata about your app, such as name, description, icons, and more.

To add an app manifest to the website:

  1. In Visual Studio Code, press Ctrl+N to create a new file with the following content, and save the file as manifest.json.

    {
        "lang": "en-us",
        "name": "My Sample PWA",
        "short_name": "SamplePWA",
        "description": "A sample PWA for testing purposes",
        "start_url": "/",
        "background_color": "#2f3d58",
        "theme_color": "#2f3d58",
        "orientation": "any",
        "display": "standalone",
        "icons": [
            {
                "src": "/icon512.png",
                "sizes": "512x512"
            }
        ]
    }
    
  2. Add a 512x512 pixel app icon image named icon512.png to your project. You can use the sample image for testing purposes.

  3. In Visual Studio Code, open index.html, and add the following code inside the <head> tag.

    <link rel="manifest" href="/manifest.json">
    

The above code snippet links the new web app manifest file to your website.

Your VS Code project should now look somewhat like this:

Screenshot of VS Code showing the sample PWA project, with the index.html, manifest.json, and icon files

Step 3 - Add a Service Worker

Service workers are the key technology behind PWAs. Service workers enable scenarios that were previously limited to native apps, including:

  • Offline support.
  • Advanced caching.
  • Running background tasks.

Service workers are specialized Web Workers that intercept network requests from your PWA. Service workers can run tasks even when your PWA isn't running, including:

  • Serving requested resources from a cache.
  • Sending push notifications.
  • Running background fetch tasks.
  • Badging icons.

Service workers are defined in a special JavaScript file, described in Using Service Workers and Service Worker API.

To add a service worker in your project:

  1. In VS Code, create a new file (Ctrl+N), add the following content, and save the file as sw.js:

    const CACHE_NAME = `my-sample-app-cache-v1`;
    
    // Use the install event to pre-cache all initial resources.
    self.addEventListener('install', event => {
      event.waitUntil((async () => {
        const cache = await caches.open(CACHE_NAME);
        cache.addAll(['/']);
      })());
    });
    
    self.addEventListener('fetch', event => {
      event.respondWith((async () => {
        const cache = await caches.open(CACHE_NAME);
    
        try {
          // Try to fetch the resource from the network.
          const fetchResponse = await fetch(event.request);
    
          // Save the resource in the cache.
          cache.put(event.request, fetchResponse.clone());
    
          // And return it.
          return fetchResponse;
        } catch (e) {
          // Fetching didn't work get the resource from the cache.
          const cachedResponse = await cache.match(event.request);
    
          // And return it.
          return cachedResponse;
        }
      })());
    });
    

    The sw.js file will act as your PWA's service worker. The code above listens to the install event and uses it to cache the request to the home page. The code also intercepts fetch events, which happen every time your app sends a request to the server, and applies a network-first strategy. The service worker relays requests to the server, and caches the result. When a network request fails, the cached response is used instead.

  2. Open index.html and add the following code at the end of the <body> tag to register your servier worker:

    <script>
    if('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js', { scope: '/' });
    }
    </script>
    

To confirm that your service worker is running:

  1. Go to your web app at http://localhost:8080.

  2. In Microsoft Edge, press F12 to open DevTools. Open the Application tool, then Service Workers to view the service workers. If the service worker isn't displayed, refresh the page.

    The DevTools Application tool, showing the Service Workers panel, with the new sw.js worker running

  3. View the service worker cache by expanding Cache Storage and selecting my-sample-app-cache-v1. All of the resources cached by the service worker should be displayed. The resources cached by the service worker include the app icon, app manifest, and the initial page.

    DevTools, showing where to view the cached resources

  4. Try your PWA as an offline app. In DevTools, open the Network tool, and change the Throttling value to Offline.

  5. Refresh your app. It should still appear correctly in the browser, using cached resources served by the service worker.

    DevTools, showing where to switch the Throttling value to Offline

Install the app

Now that your simple website has a web app manifest and a service worker, supporting browsers can install it as a PWA.

In Microsoft Edge, once you refresh your app, the App available button appears in the address bar. Clicking the App available button prompts you to install the app locally.

Microsoft Edge, with the sample PWA in a tab. The App available button in the address bar has been clicked and the installation prompt is displayed

Click Install to install the app locally. After the installation completes, your app is displayed in its own window, and its own application icon in the Taskbar.

The sample PWA, installed and running in its own window

To learn more about installing PWAs, see The user experience of PWAs.

Best practices and next steps

To build a robust, real-world PWA, consider the following best practices for web app development.

Cross-browser compatibility

Test your app for cross-browser compatibility. Make sure your PWA works, by testing it in different browsers and environments. See Tools at Microsoft Edge Developer.

Responsive design

Use fluid layouts and flexible images. Responsive design includes the following elements that adapt your UX to your user's device:

To test your app locally, use device emulation tools from your browser. To test your app directly on a target device, create a remote debugging session on Windows or Android.

Support deep linking

Support Deep linking. Route each page of your site to a unique URL so existing users can help you engage an even broader audience through social media sharing.

Provide a rich offline experience

Provide a rich Offline experience. Make the app work even if the user's device is offline. Provide a custom offline page rather than using the browser's default offline page.

Use validation and testing practices

Use software validation and testing practices. Use code quality tools such as Webhint to optimize the efficiency, robustness, safety, and accessibility of your app. Use automated testing tools such as Playwright to create reliable end-to-end testing for your app.

See also