Offline-First Strategy with Blazor PWAs: A Complete Guide 🚀

One of the most powerful features of Progressive Web Apps (PWAs) is their ability to function seamlessly even when offline. For users, this means uninterrupted access to critical features regardless of network conditions. For developers, adopting an offline-first strategy ensures a robust, user-friendly experience while aligning with modern web development best practices.

Blazor, Microsoft’s modern web framework, simplifies building PWAs with offline capabilities by leveraging features like service workers, caching, and IndexedDB. In this guide, we’ll dive into how you can implement an offline-first strategy in your Blazor PWA.

---

Why Offline-First Matters

An offline-first strategy doesn’t just improve user experience—it also provides:

• Reliability: Apps remain functional even with intermittent or no connectivity.
• Performance: Cached assets load faster, improving responsiveness.
• Engagement: Users can interact with the app at any time, enhancing retention and trust.

---

Key Components of Offline-First Blazor PWAs

1. Service Workers
   A service worker is a background script that intercepts network requests, enabling features like caching and offline support. Blazor PWAs come with a pre-configured service worker that you can extend to meet your needs.

2. Caching Strategies
   Caching is the cornerstone of offline functionality, ensuring that assets and data are available even when the network isn’t.

3. Data Synchronization
   For dynamic apps, local storage of user data and synchronization with a backend API when online are crucial.

---

Step 1: Setting Up a Blazor PWA

If you don’t already have a Blazor PWA, create one with the following command:

dotnet new blazorwasm -o OfflineBlazorPWA --pwa
cd OfflineBlazorPWA

This sets up a Blazor WebAssembly project with essential PWA features, including a service worker and a manifest file.

Run the app:

dotnet run

Visit http://localhost:5000 to see your PWA in action.

---

Step 2: Customizing the Service Worker

The service worker (located in wwwroot/service-worker.js) enables offline support by caching assets. Open this file to customize its behavior.

Example: Caching Assets

Add essential files to the cache during the service worker's install event:

self.addEventListener('install', event => {
    event.waitUntil(
        caches.open('offline-cache').then(cache => {
            return cache.addAll([
                '/',
                '/index.html',
                '/css/app.css',
                '/_framework/blazor.webassembly.js'
            ]);
        })
    );
});

Fetch from Cache First

Intercept network requests to serve assets from the cache:

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

This ensures faster responses and allows the app to function offline.

---

Step 3: Caching Dynamic Data

For apps that rely on API data, caching dynamic responses is essential. Use IndexedDB, a browser-based database, to store and retrieve API responses.

Example: Storing API Responses

Use Blazor’s IndexedDB libraries or JavaScript interop to manage dynamic data caching.

Define an IndexedDB Context: Install a library like Blazor.IndexedDB:

dotnet add package Blazor.IndexedDB

Configure a database context:

public class AppDbContext : IndexedDb
{
    public AppDbContext(IndexedDBOptions<AppDbContext> options) : base(options) { }
    public IndexedSet<Product> Products { get; set; }
}

Save API Data to IndexedDB:

private async Task FetchAndCacheDataAsync()
{
    var data = await Http.GetFromJsonAsync<List<Product>>("api/products");
    foreach (var product in data)
    {
        await DbContext.Products.AddAsync(product);
    }
    await DbContext.SaveChangesAsync();
}

Retrieve Data Offline:

private async Task<List<Product>> GetCachedDataAsync()
{
    return await DbContext.Products.ToListAsync();
}

---

Step 4: Data Synchronization

Synchronizing locally stored data with a backend API ensures consistency once the user is online.

Sync Logic Example:

1. Store user actions offline.
2. Detect connectivity changes.
3. Sync data when the user goes online.

Track Offline Actions:

private async Task SaveOfflineActionAsync(Order order)
{
    var actions = await LocalStorage.GetItemAsync<List<Order>>("offlineOrders") ?? new List<Order>();
    actions.Add(order);
    await LocalStorage.SetItemAsync("offlineOrders", actions);
}

Sync on Reconnection:

private async Task SyncDataAsync()
{
    var offlineOrders = await LocalStorage.GetItemAsync<List<Order>>("offlineOrders");
    if (offlineOrders != null && offlineOrders.Any())
    {
        foreach (var order in offlineOrders)
        {
            await Http.PostAsJsonAsync("api/orders", order);
        }
        await LocalStorage.RemoveItemAsync("offlineOrders");
    }
}

Use an event listener to detect connectivity changes:

window.addEventListener('online', () => {
    DotNet.invokeMethodAsync('OfflineBlazorPWA', 'SyncDataAsync');
});

---

Step 5: Testing Your Offline PWA

1. Run your app locally (dotnet run).
2. Open the app in your browser and enable offline mode in DevTools:
   • Chrome: Go to Application > Service Workers and check "Offline".
   • Edge: Navigate to Developer Tools > Application.
3. Verify the app’s functionality, including:
   • Loading static assets.
   • Retrieving cached API data.
   • Saving user actions for synchronization.

---

Step 6: Deploying Your Offline PWA

Once your offline features are implemented, deploy your PWA to a hosting platform like Azure, Firebase Hosting, or GitHub Pages.

Deploy to Azure Static Web Apps:

az staticwebapp create \
  --name OfflineBlazorPWA \
  --source-location ./ \
  --output-location ./bin/Release/net7.0/publish/wwwroot \
  --branch main

---

Best Practices for Offline-First Blazor PWAs

1. Optimize Cache Management: Regularly update cached assets to avoid serving outdated content. Use cache versioning to control this process.

   
   const CACHE_NAME = 'offline-cache-v2';
   

2. Handle Edge Cases: Gracefully handle scenarios where data can’t sync due to conflicts or server issues.

3. Monitor Service Workers: Use browser tools to debug and test service worker behavior.

4. Communicate with Users: Notify users when they are offline or when data is syncing.

---

Conclusion

An offline-first strategy enhances the reliability, performance, and user experience of your Blazor PWA. By leveraging service workers for caching, IndexedDB for dynamic data, and robust synchronization logic, you can ensure that your app remains functional even in challenging network conditions.

Ready to dive deeper into Blazor and PWAs? Check out my book, Building Progressive Web Apps with Blazor, for more insights, real-world examples, and advanced techniques.

Let’s make the web more reliable—one offline-ready app at a time! 🚀