Claude Code for PWA Install Prompt Workflow Guide

Progressive Web Apps (PWAs) have become an essential part of modern web development, offering an app-like experience directly from the browser. One of the most powerful features of PWAs is the ability to prompt users to install your app on their device. In this guide, we’ll explore how to use Claude Code to implement a complete PWA install prompt workflow, complete with service worker setup, custom UI, and best practices.

Understanding the PWA Install Prompt

Before diving into implementation, it’s important to understand how the PWA install prompt works. The browser provides a beforeinstallprompt event that fires when your PWA meets the installation criteria. However, browsers have specific requirements before this event fires:

Your app must have a web app manifest with at least the name or short_name, icons, and start_url fields
The service worker must be registered and functional
Your app must be served over HTTPS
Users must visit your site at least twice (with at least 5 minutes between visits)

Claude Code can help you set up all these requirements systematically. Let’s start by creating the necessary files.

Setting Up Your PWA Manifest

The first step is creating a proper web app manifest. Ask Claude Code to generate this file for you:

// public/manifest.json
{
  "name": "My PWA App",
  "short_name": "MyApp",
  "description": "A powerful Progressive Web App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4a90e2",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

Make sure to include this manifest in your HTML file:

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

Creating the Service Worker

Your PWA needs a service worker to function properly. Here’s a basic service worker setup:

// public/sw.js
const CACHE_NAME = 'my-pwa-v1';
const urlsToCache = [
  '/',
  '/index.html',
  '/styles.css',
  '/script.js'
];

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

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then((response) => response || fetch(event.request))
  );
});

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then((registration) => {
        console.log('Service Worker registered:', registration);
      })
      .catch((error) => {
        console.error('Service Worker registration failed:', error);
      });
  });
}

Implementing the Install Prompt Handler

Now comes the core logic for handling the install prompt. Here’s a complete implementation:

// js/pwa-install.js
let deferredPrompt;
const installButton = document.getElementById('install-button');
const installBanner = document.getElementById('install-banner');

// Hide the button by default until the event fires
installButton.style.display = 'none';

window.addEventListener('beforeinstallprompt', (event) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  event.preventDefault();
  
  // Stash the event so it can be triggered later
  deferredPrompt = event;
  
  // Show your custom install UI
  installButton.style.display = 'block';
  installBanner.style.display = 'flex';
});

installButton.addEventListener('click', async () => {
  if (!deferredPrompt) return;
  
  // Show the prompt
  deferredPrompt.prompt();
  
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  
  // Clear the deferredPrompt
  deferredPrompt = null;
  
  // Hide your custom UI
  installButton.style.display = 'none';
  installBanner.style.display = 'none';
  
  console.log(`User response to install prompt: ${outcome}`);
});

// Handle successful installation
window.addEventListener('appinstalled', (event) => {
  console.log('PWA was installed successfully');
  
  // Track installation analytics
  ga('send', 'event', 'PWA', 'Installed');
  
  // Optionally hide any remaining install prompts
  installBanner.style.display = 'none';
});

Creating a User-Friendly Install UI

The default browser install prompt is limited, so creating a custom UI can significantly improve your conversion rate. Here’s a stylish banner implementation:

<div id="install-banner" class="install-banner" style="display: none;">
  <div class="install-content">
    <img src="/icons/icon-48x48.png" alt="App Icon" class="app-icon">
    <div class="install-text">
      <h3>Install MyApp</h3>
      <p>Add to your home screen for the full experience</p>
    </div>
    <button id="install-button" class="install-btn">Install</button>
    <button id="dismiss-banner" class="dismiss-btn">&times;</button>
  </div>
</div>

<style>
.install-banner {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  background: white;
  box-shadow: 0 -2px 10px rgba(0,0,0,0.1);
  padding: 16px;
  z-index: 1000;
}

.install-content {
  display: flex;
  align-items: center;
  max-width: 800px;
  margin: 0 auto;
  gap: 16px;
}

.app-icon {
  width: 48px;
  height: 48px;
  border-radius: 8px;
}

.install-text {
  flex: 1;
}

.install-text h3 {
  margin: 0;
  font-size: 16px;
}

.install-text p {
  margin: 4px 0 0;
  font-size: 14px;
  color: #666;
}

.install-btn {
  background: #4a90e2;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 600;
}

.dismiss-btn {
  background: none;
  border: none;
  font-size: 24px;
  cursor: pointer;
  color: #999;
}
</style>

Best Practices for PWA Install Prompts

Implementing the install prompt is only half the battle. Here are best practices to maximize your installation rate:

Timing is Everything

Don’t show the install prompt immediately when users land on your site. Instead, wait until users have engaged with your app:

let engagementCount = 0;

function trackEngagement() {
  engagementCount++;
  
  // Show install prompt after meaningful engagement
  if (engagementCount >= 3 && !localStorage.getItem('pwa-installed')) {
    showInstallPrompt();
  }
}

// Track various engagement events
document.addEventListener('click', trackEngagement);
document.addEventListener('scroll', trackEngagement);

Respect User Decisions

If users dismiss your install prompt, don’t show it again immediately. Use localStorage to track this:

const DISMISSED_KEY = 'pwa-install-dismissed';
const DISMISSED_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days

document.getElementById('dismiss-banner').addEventListener('click', () => {
  const now = Date.now();
  localStorage.setItem(DISMISSED_KEY, now.toString());
  installBanner.style.display = 'none';
});

function shouldShowInstallPrompt() {
  const dismissed = localStorage.getItem(DISMISSED_KEY);
  if (!dismissed) return true;
  
  const dismissedTime = parseInt(dismissed);
  return (Date.now() - dismissedTime) > DISMISSED_DURATION;
}

Provide Value in the Prompt

Users are more likely to install your PWA when they understand the benefits. Include value propositions in your prompt:

const installBanner = document.getElementById('install-banner');

function updateBannerContent() {
  const textElement = installBanner.querySelector('p');
  const benefits = [
    'Offline access to your data',
    'Faster loading times',
    'Add to home screen for quick access',
    'Native app-like experience'
  ];
  
  // Rotate through benefits or show personalized ones
  textElement.textContent = benefits.join(' • ');
}

Testing Your PWA Install Flow

Before deploying, thoroughly test your PWA install flow. Claude Code can help you verify:

Manifest validation - Ensure all required fields are present
Service worker registration - Check for errors in the console
Icon display - Verify all icon sizes render correctly
Cross-browser testing - Test on Chrome, Firefox, Safari, and Edge
Mobile testing - Test on actual devices or emulators

Use Lighthouse in Chrome DevTools to audit your PWA:

# In Chrome DevTools
# 1. Open DevTools (F12)
# 2. Go to Lighthouse tab
# 3. Select "Progressive Web App" category
# 4. Click "Analyze page load"

Conclusion

Implementing a PWA install prompt workflow doesn’t have to be complicated. With Claude Code helping you generate the necessary files and code snippets, you can set up a complete installation flow in under an hour. Remember to focus on user experience by timing your prompts appropriately, providing clear value propositions, and respecting user decisions. A well-implemented install prompt can significantly increase your PWA’s installation rate and user engagement.

The key is to balance visibility with user experience—show the prompt to engaged users, but never force it. With these patterns and practices, you’re well on your way to building a successful PWA install workflow.

Built by theluckystrike — More at zovo.one