Mobile Development•Monday, December 8, 2025

Progressive Web App From Scratch: A Developer's Guide

Braine Agency
Progressive Web App From Scratch: A Developer's Guide
```html PWA From Scratch: A Developer's Guide | Braine Agency

In today's mobile-first world, users demand seamless and engaging experiences. Progressive Web Apps (PWAs) offer a powerful solution, bridging the gap between native mobile apps and traditional websites. At Braine Agency, we're passionate about building cutting-edge web solutions, and PWAs are a key part of that. This comprehensive guide will walk you through the process of building a PWA from scratch, empowering you to create fast, reliable, and engaging web experiences.

What is a Progressive Web App (PWA)?

A Progressive Web App (PWA) is a website that behaves like a native mobile application. It leverages modern web technologies to provide an enhanced user experience, offering features such as:

  • Reliability: PWAs load instantly and work offline or on low-quality networks thanks to service workers.
  • Fast Loading: Optimized performance ensures a smooth and responsive user experience.
  • Engaging: PWAs can be installed on the user's home screen, send push notifications, and access device hardware features.

According to Google, users spend 87% of their time in apps, but mobile websites reach 3x more people. PWAs offer the best of both worlds, combining the reach of the web with the engagement of native apps. This makes them an ideal solution for businesses looking to expand their mobile presence without the complexity and cost of native app development.

Why Build a PWA?

Building a PWA offers numerous benefits for your users and your business:

  • Improved User Experience: Fast loading times, offline access, and app-like features contribute to a more engaging and satisfying user experience.
  • Increased Engagement: Home screen installation and push notifications drive user retention and repeat visits.
  • Enhanced SEO: PWAs are easily discoverable through search engines, improving your website's visibility and organic traffic.
  • Reduced Development Costs: Developing a PWA is typically faster and less expensive than building separate native apps for iOS and Android.
  • Cross-Platform Compatibility: PWAs work on any device with a modern web browser.
  • Offline Functionality: Even when there's no internet connection, users can still access previously visited content and perform certain tasks.

Data shows that PWAs can significantly improve key metrics. For example, Twitter Lite, a PWA, saw a 65% increase in pages per session, a 75% increase in Tweets sent, and a 20% decrease in bounce rate.

Building Your First PWA: A Step-by-Step Guide

Let's dive into the practical steps of building a PWA from scratch. We'll cover the essential components and provide code examples to get you started.

1. Setting Up Your Development Environment

Before you begin, ensure you have the following tools installed:

  • A Code Editor: VS Code, Sublime Text, or Atom are popular choices.
  • Node.js and npm (Node Package Manager): Used for managing dependencies and running development servers.
  • A Modern Web Browser: Chrome, Firefox, or Safari are recommended for testing your PWA.

Create a new project directory and initialize it with npm:


  mkdir my-pwa
  cd my-pwa
  npm init -y

2. Creating the Manifest File (manifest.json)

The manifest file is a JSON file that provides metadata about your PWA to the browser. It includes information such as the app's name, icons, start URL, and display mode. This allows the browser to install the PWA on the user's home screen and display it in a native app-like way.

Create a file named manifest.json in your project directory and add the following content:


  {
    "name": "My Awesome PWA",
    "short_name": "AwesomePWA",
    "start_url": "/",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#007bff",
    "icons": [
      {
        "src": "/icons/icon-192x192.png",
        "sizes": "192x192",
        "type": "image/png"
      },
      {
        "src": "/icons/icon-512x512.png",
        "sizes": "512x512",
        "type": "image/png"
      }
    ]
  }

Explanation:

  • name: The full name of your PWA.
  • short_name: A shorter name for display on the home screen.
  • start_url: The URL that opens when the PWA is launched.
  • display: Specifies how the PWA should be displayed (e.g., standalone for a native app-like experience).
  • background_color: The background color of the splash screen.
  • theme_color: The color of the browser's address bar.
  • icons: An array of icon objects, each specifying the source, size, and type of an icon. You'll need to create these icon files and place them in an icons directory.

Important: Generate icons in various sizes (e.g., 48x48, 72x72, 96x96, 144x144, 192x192, 512x512) to ensure optimal display on different devices. There are many online tools available for generating icons from a single image.

3. Creating the Service Worker (service-worker.js)

The service worker is the heart of your PWA. It's a JavaScript file that runs in the background, intercepting network requests, caching resources, and providing offline functionality. It acts as a proxy between your web app and the network.

Create a file named service-worker.js in your project directory and add the following code:


  const CACHE_NAME = 'my-pwa-cache-v1';
  const urlsToCache = [
    '/',
    '/index.html',
    '/style.css',
    '/script.js',
    '/icons/icon-192x192.png',
    '/icons/icon-512x512.png'
  ];

  self.addEventListener('install', event => {
    event.waitUntil(
      caches.open(CACHE_NAME)
        .then(cache => {
          console.log('Opened cache');
          return cache.addAll(urlsToCache);
        })
    );
  });

  self.addEventListener('fetch', event => {
    event.respondWith(
      caches.match(event.request)
        .then(response => {
          // Cache hit - return response
          if (response) {
            return response;
          }

          // Not in cache - fetch from network
          return fetch(event.request).then(
            function(response) {
              // Check if we received a valid response
              if(!response || response.status !== 200 || response.type !== 'basic') {
                return response;
              }

              // IMPORTANT: Clone the response. A response is a stream
              // and because we want the browser to consume the response
              // as well as the cache consuming the response, we need
              // to clone it so we have two independent copies.
              var responseToCache = response.clone();

              caches.open(CACHE_NAME)
                .then(function(cache) {
                  cache.put(event.request, responseToCache);
                });

              return response;
            }
          );
        })
    );
  });

  self.addEventListener('activate', event => {
    const cacheWhitelist = [CACHE_NAME];

    event.waitUntil(
      caches.keys().then(cacheNames => {
        return Promise.all(
          cacheNames.map(cacheName => {
            if (cacheWhitelist.indexOf(cacheName) === -1) {
              return caches.delete(cacheName);
            }
          })
        );
      })
    );
  });

Explanation:

  • CACHE_NAME: A unique name for your cache. Increment this when you change the service worker to force an update.
  • urlsToCache: An array of URLs to cache when the service worker is installed. This should include all static assets like HTML, CSS, JavaScript, and images.
  • install event: Called when the service worker is installed. It opens a cache and adds the specified URLs to it.
  • fetch event: Called when the browser makes a network request. It checks if the request is already in the cache. If so, it returns the cached response. Otherwise, it fetches the resource from the network, caches it, and returns the response.
  • activate event: Called when a new service worker is activated. It cleans up old caches.

4. Registering the Service Worker in Your HTML

To register the service worker, add the following code to your index.html file:


  
  
  
    
    My Awesome PWA
    
    
    
    
    
  
  
    
Hello, PWA!

    
This is my first Progressive Web App.

Explanation:

  • <link rel="manifest" href="/manifest.json">: Links your HTML to the manifest file.
  • <meta name="viewport" content="width=device-width, initial-scale=1">: Configures the viewport for mobile devices.
  • <link rel="apple-touch-icon" href="/icons/icon-192x192.png">: Specifies the icon for iOS devices when the PWA is added to the home screen.
  • <meta name="theme-color" content="#007bff"/>: Sets the theme color for the browser's address bar.
  • The JavaScript code checks if the browser supports service workers and registers the service-worker.js file.

5. Testing Your PWA

To test your PWA, you'll need to serve it over HTTPS. You can use a local development server like http-server:


  npm install -g http-server
  http-server -S -C cert.pem -K key.pem

You'll likely need to generate self-signed certificates for HTTPS. There are many guides available online for doing this, depending on your operating system.

Open your browser's developer tools (usually by pressing F12) and navigate to the "Application" or "Service Workers" tab. You should see your service worker registered and running. You can also simulate offline conditions to test the PWA's offline functionality.

6. Making it Beautiful: Adding CSS

While functionality is crucial, a good user experience relies on a visually appealing design. Let's create a simple style.css file:


  body {
    font-family: sans-serif;
    margin: 20px;
    line-height: 1.6;
  }

  h1 {
    color: #333;
  }

  p {
    color: #666;
  }

Remember to include this in your urlsToCache array in your service-worker.js file so it's available offline.

7. Adding Interactivity with JavaScript

Let's add some simple JavaScript to our script.js file to demonstrate interactivity:


  document.addEventListener('DOMContentLoaded', () => {
    const heading = document.querySelector('h1');
    heading.addEventListener('click', () => {
      alert('You clicked the heading!');
    });
  });

Again, remember to include this in your urlsToCache array.

Advanced PWA Features

Once you have a basic PWA up and running, you can explore more advanced features to enhance the user experience:

  • Push Notifications: Send timely updates and reminders to users, even when they're not actively using your PWA. This requires a backend service and integration with push notification services like Firebase Cloud Messaging (FCM).
  • Background Sync: Allow users to perform actions offline, and synchronize the data with the server when a connection is available.
  • Web Share API: Enable users to share content from your PWA with other apps and services.
  • Payment Request API: Simplify the payment process for users.
  • Geolocation API: Access the user's location to provide location-based services.

Best Practices for Building PWAs

To ensure your PWA delivers a great user experience and achieves its goals, follow these best practices:

  1. Prioritize Performance: Optimize your code, images, and other assets to ensure fast loading times. Use tools like Lighthouse to identify performance bottlenecks.
  2. Ensure Offline Functionality: Provide a meaningful offline experience, even if it's just displaying a cached version of your content.
  3. Design for Mobile First: Create a responsive design that adapts to different screen sizes and devices.
  4. Use HTTPS: PWAs require HTTPS to ensure secure communication.
  5. Test Thoroughly: Test your PWA on different devices and browsers to ensure compatibility and a consistent user experience.
  6. Use a Service Worker Lifecycle Management Library: Libraries like Workbox can simplify service worker management and caching strategies.

Common PWA Mistakes to Avoid

When building PWAs, it's important to be aware of common mistakes that can negatively impact the user experience:

  • Not providing a fallback for offline content: Users should always see something, even when offline.
  • Over-caching
More from Braine Agency