SilverLABS.SilverSHELL.PWA

Progressive Web App (PWA) support for SilverSHELL applications.

Features

• ✨ NEW: Ready-Made PWA Assets - Includes pwa.js and service-worker.js out of the box!
• Offline Support - Work without internet connection
• Installable - Add to home screen on mobile/desktop
• Service Worker - Automatic caching and background sync with multiple strategies
• App Manifest - Configure PWA appearance and behavior
• Install Prompt - Custom installation UI with JavaScript interop
• Theme Customization - Brand colors and styling
• Update Notifications - Alert users of new versions
• Offline Detection - Automatic online/offline status tracking

Installation

dotnet add package SilverLABS.SilverSHELL.PWA

Quick Start

1. Configure PWA Services

using SilverSHELL.PWA.Extensions;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Services.AddSilverShellPWA(options =>
{
    options.AppName = "My Application";
    options.ShortName = "MyApp";
    options.Description = "My awesome PWA application";
    options.EnableOfflineSupport = true;
    options.ShowInstallPrompt = true;
    options.ThemeColor = "#2196F3";
    options.BackgroundColor = "#ffffff";
});

await builder.Build().RunAsync();

2. Include PWA Scripts (✨ NEW in v1.1.0 - Automatically Included!)

Add these to your wwwroot/index.html before the closing </head> tag:

<!-- Service Worker & PWA Support -->
<script src="_content/SilverSHELL.PWA/service-worker.js"></script>
<script src="_content/SilverSHELL.PWA/pwa.js"></script>

That's it! The package now includes production-ready PWA assets. No need to create your own service worker!

3. Add Service Worker (Optional - Manual Approach)

If you prefer a custom service worker, create wwwroot/service-worker.js:

self.addEventListener('install', event => {
    console.log('Service worker installing...');
    self.skipWaiting();
});

self.addEventListener('activate', event => {
    console.log('Service worker activating...');
});

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

3. Register Service Worker

In index.html:

<script>
    if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/service-worker.js')
            .then(reg => console.log('Service worker registered'))
            .catch(err => console.log('Service worker registration failed'));
    }
</script>

4. Add Web Manifest

Create wwwroot/manifest.json:

{
  "name": "My Application",
  "short_name": "MyApp",
  "description": "My awesome PWA",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#2196F3",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Link in index.html:

<link rel="manifest" href="manifest.json" />
<link rel="apple-touch-icon" href="icon-192.png" />
<meta name="theme-color" content="#2196F3" />

Configuration Options

PWAOptions

public class PWAOptions
{
    /// <summary>
    /// Full application name
    /// </summary>
    public string AppName { get; set; } = "SilverSHELL App";

    /// <summary>
    /// Short name for home screen
    /// </summary>
    public string ShortName { get; set; } = "SilverSHELL";

    /// <summary>
    /// Application description
    /// </summary>
    public string Description { get; set; } = "Progressive Web Application";

    /// <summary>
    /// Enable offline functionality
    /// </summary>
    public bool EnableOfflineSupport { get; set; } = true;

    /// <summary>
    /// Show install prompt to users
    /// </summary>
    public bool ShowInstallPrompt { get; set; } = true;

    /// <summary>
    /// Theme color (hex)
    /// </summary>
    public string ThemeColor { get; set; } = "#2196F3";

    /// <summary>
    /// Background color (hex)
    /// </summary>
    public string BackgroundColor { get; set; } = "#ffffff";
}

Advanced Features

1. Custom Install Prompt

@inject IJSRuntime JS
@inject IOptions<PWAOptions> PWAOptions

@if (showInstallPrompt && PWAOptions.Value.ShowInstallPrompt)
{
    <div class="install-prompt">
        <p>Install @PWAOptions.Value.AppName for a better experience!</p>
        <button @onclick="InstallApp">Install</button>
        <button @onclick="DismissPrompt">Not now</button>
    </div>
}

@code {
    private bool showInstallPrompt = true;

    private async Task InstallApp()
    {
        await JS.InvokeVoidAsync("installPWA");
        showInstallPrompt = false;
    }

    private void DismissPrompt()
    {
        showInstallPrompt = false;
    }
}

2. Offline Detection

@inject IJSRuntime JS

<div class="@(isOnline ? "online" : "offline")">
    @(isOnline ? "✅ Online" : "⚠️ Offline")
</div>

@code {
    private bool isOnline = true;

    protected override async Task OnInitializedAsync()
    {
        isOnline = await JS.InvokeAsync<bool>("navigator.onLine");
    }
}

3. Update Notification

@if (updateAvailable)
{
    <div class="update-notification">
        <p>A new version is available!</p>
        <button @onclick="ReloadApp">Update Now</button>
    </div>
}

@code {
    private bool updateAvailable = false;

    private async Task ReloadApp()
    {
        await JS.InvokeVoidAsync("location.reload", true);
    }
}

Service Worker Strategies

1. Cache-First Strategy

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

2. Network-First Strategy

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

3. Stale-While-Revalidate

self.addEventListener('fetch', event => {
    event.respondWith(
        caches.open('dynamic').then(cache => {
            return fetch(event.request).then(response => {
                cache.put(event.request, response.clone());
                return response;
            }).catch(() => cache.match(event.request));
        })
    );
});

Best Practices

1. Always test offline - Use Chrome DevTools to simulate offline mode
2. Cache strategically - Only cache essential resources
3. Version your cache - Update cache name on new releases
4. Handle updates gracefully - Notify users of new versions
5. Provide icons - Include 192x192 and 512x512 PNG icons
6. Use HTTPS - PWAs require secure connections

Documentation

• Full Documentation
• PWA Best Practices
• Service Worker API

Support

• Issues: GitLab Issues
• Email: support@silverlabs.uk

Changelog

v1.1.0

• ✨ NEW: Included ready-made PWA assets (pwa.js and service-worker.js)
• ✨ NEW: Install prompt handling with JavaScript interop (SilverShellPWA.install())
• ✨ NEW: Offline detection with automatic CSS classes (pwa-online, pwa-offline)
• ✨ NEW: Service worker update notifications
• ✨ NEW: Multiple caching strategies (cache-first, network-first, stale-while-revalidate)
• ✨ NEW: Background sync and push notification support
• 🔧 IMPROVED: Changed to Razor SDK for static web asset support
• 🔧 IMPROVED: No manual service worker creation required
• 📚 DOCS: Updated README with automatic asset inclusion instructions

v1.0.0

• Initial release

License

This project is licensed under the MIT License.

Made with ❤️ by SilverLABS