DEV Community: Oghenetega Adiri

Building Robust Offline Functionality in React Native: A Complete Guide

Oghenetega Adiri — Wed, 22 Oct 2025 05:26:42 +0000

Introduction

In today's mobile-first world, users expect apps to work seamlessly regardless of network connectivity. Whether you're building a visitor management system, a field service app, or any data-driven application, implementing robust offline functionality is crucial for delivering a great user experience.

In this comprehensive guide, I'll walk you through building a production-ready offline system in React Native, covering everything from data synchronization to conflict resolution. We'll explore real-world implementations from a visitor management system that handles offline code verification, queue management, and intelligent sync strategies.

Architecture Overview
Storage Strategy
Network State Management
Offline Queue Implementation
Data Synchronization
Context-Based State Management
Handling Edge Cases
Best Practices

Architecture Overview

Our offline system follows a three-layer architecture:

Storage Layer: Handles persistent data storage using AsyncStorage and SecureStore
Service Layer: Manages business logic, API calls, and offline fallbacks
Context Layer: Provides global state management and sync coordination

┌─────────────────────────────────────┐
│     UI Components (Screens)         │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│    Context Providers                │
│  (AppContext, CodeContext, etc.)    │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│       Service Layer                 │
│  (CodeService, NetworkService)      │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│      Storage Layer                  │
│  (AsyncStorage, SecureStore)        │
└─────────────────────────────────────┘

Storage Strategy

Handling Storage Size Limits

React Native's SecureStore has a 2KB limit, which can be problematic for larger data structures. Here's how to handle it elegantly:

import * as SecureStore from 'expo-secure-store';
import AsyncStorage from '@react-native-async-storage/async-storage';

const SECURE_STORE_SIZE_LIMIT = 2000;

class EnhancedSecureStorage {
  static async setItem(key, value, options = {}) {
    try {
      const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
      const byteSize = new Blob([stringValue]).size;

      // If value exceeds limit, use AsyncStorage with overflow handling
      if (byteSize > SECURE_STORE_SIZE_LIMIT) {
        console.warn(`${key} is ${byteSize} bytes, using AsyncStorage`);

        await AsyncStorage.setItem(`secure_overflow_${key}`, stringValue);
        await SecureStore.setItemAsync(
          key, 
          `__OVERFLOW__:secure_overflow_${key}`, 
          options
        );
        return;
      }

      await SecureStore.setItemAsync(key, stringValue, options);
    } catch (error) {
      // Fallback logic
      if (error.message?.includes('too large')) {
        const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
        await AsyncStorage.setItem(`secure_overflow_${key}`, stringValue);
        await SecureStore.setItemAsync(
          key, 
          `__OVERFLOW__:secure_overflow_${key}`, 
          options
        );
      } else {
        throw error;
      }
    }
  }

  static async getItem(key) {
    const value = await SecureStore.getItemAsync(key);

    if (!value) return null;

    // Handle overflow references
    if (value.startsWith('__OVERFLOW__:')) {
      const asyncStorageKey = value.replace('__OVERFLOW__:', '');
      return await AsyncStorage.getItem(asyncStorageKey);
    }

    return value;
  }
}

Structured Storage with Metadata

Always store data with metadata for better cache management:

export const storeOfflineCodes = async (codes, syncTime = null) => {
  try {
    const data = {
      codes: codes || [],
      lastSync: syncTime || new Date().toISOString(),
      version: '1.0'
    };

    await AsyncStorage.setItem(
      STORAGE_KEYS.OFFLINE_CODES, 
      JSON.stringify(data)
    );
    await AsyncStorage.setItem(STORAGE_KEYS.LAST_SYNC, data.lastSync);

    return { success: true };
  } catch (error) {
    console.error('Error storing offline codes:', error);
    return { success: false, error: error.message };
  }
};

export const getOfflineCodes = async () => {
  try {
    const data = await AsyncStorage.getItem(STORAGE_KEYS.OFFLINE_CODES);

    if (data) {
      const parsedData = JSON.parse(data);

      // Handle legacy format
      if (Array.isArray(parsedData)) {
        return { codes: parsedData, lastSync: null, success: true };
      }

      // Handle new format with metadata
      return { 
        codes: parsedData.codes || [], 
        lastSync: parsedData.lastSync,
        version: parsedData.version,
        success: true 
      };
    }

    return { codes: [], lastSync: null, success: true };
  } catch (error) {
    console.error('Error getting offline codes:', error);
    return { codes: [], lastSync: null, success: false };
  }
};

Network State Management

Robust network detection is crucial. Use @react-native-community/netinfo for reliable network state monitoring:

import NetInfo from '@react-native-community/netinfo';

// In your AppContext or service
useEffect(() => {
  const unsubscribe = NetInfo.addEventListener(networkState => {
    const isOnline = networkState.isConnected;
    const wasOffline = !previousOnlineStatus.current;

    dispatch({
      type: 'SET_ONLINE_STATUS',
      payload: isOnline
    });

    // Trigger auto-sync when coming back online
    if (isOnline && wasOffline && settings.autoSync) {
      console.log('Network restored, triggering auto-sync...');

      // Delay to ensure stable connection
      autoSyncTimeout.current = setTimeout(() => {
        if (isMounted.current) {
          handleAutoSync();
        }
      }, 2000);
    }

    previousOnlineStatus.current = isOnline;
  });

  return () => unsubscribe();
}, []);

Offline Queue Implementation

Queue Structure

Design your offline queue to handle retry logic and failure tracking:

export const storeOfflineQueue = async (verifications) => {
  try {
    const data = {
      verifications: verifications || [],
      lastUpdated: new Date().toISOString(),
      version: '1.0'
    };

    await AsyncStorage.setItem(
      STORAGE_KEYS.OFFLINE_QUEUE, 
      JSON.stringify(data)
    );
    return { success: true };
  } catch (error) {
    return { success: false, error: error.message };
  }
};

Adding Items to Queue

When operations fail offline, queue them for later sync:

static async addToOfflineQueue(verificationData) {
  try {
    const currentQueue = await getOfflineQueue();
    const updatedQueue = [
      ...currentQueue,
      {
        ...verificationData,
        retryCount: 0,
        firstAttemptAt: new Date().toISOString(),
        lastAttemptAt: new Date().toISOString(),
      },
    ];
    await storeOfflineQueue(updatedQueue);
    return { success: true };
  } catch (error) {
    console.error('Error adding to offline queue:', error);
    return { success: false };
  }
}

Intelligent Retry Logic

Implement exponential backoff and failure handling:

static async syncOfflineVerifications() {
  const offlineQueue = await getOfflineQueue();

  if (offlineQueue.length === 0) {
    return { success: true, syncedCount: 0 };
  }

  const syncResults = [];
  const failedSyncs = [];
  const permanentFailures = [];
  const MAX_RETRY_ATTEMPTS = 5;
  const MAX_AGE_HOURS = 72; // 3 days

  for (const verification of offlineQueue) {
    const now = new Date();
    const firstAttempt = new Date(
      verification.firstAttemptAt || verification.timestamp
    );
    const ageInHours = (now - firstAttempt) / (1000 * 60 * 60);
    const retryCount = verification.retryCount || 0;

    // Check if verification is too old
    if (ageInHours > MAX_AGE_HOURS) {
      permanentFailures.push({
        ...verification,
        failureReason: 'STALE_VERIFICATION',
        failedAt: now.toISOString(),
      });
      continue;
    }

    // Check retry limit
    if (retryCount >= MAX_RETRY_ATTEMPTS) {
      permanentFailures.push({
        ...verification,
        failureReason: 'MAX_RETRIES_EXCEEDED',
        failedAt: now.toISOString(),
      });
      continue;
    }

    try {
      const response = await api.post('/codes/sync-offline-verification', {
        verificationId: verification.id,
        code: verification.code,
        offlineTimestamp: verification.timestamp,
        retryCount: retryCount,
      });

      if (response.data.success) {
        syncResults.push(verification.id);
      } else {
        // Check for permanent failures from backend
        if (response.data.permanentFailure) {
          permanentFailures.push({
            ...verification,
            failureReason: response.data.errorCode,
            serverMessage: response.data.message,
          });
        } else {
          // Retryable failure
          failedSyncs.push({
            ...verification,
            retryCount: retryCount + 1,
            lastAttemptAt: now.toISOString(),
            lastError: response.data.message,
          });
        }
      }
    } catch (error) {
      // Network errors are retryable, HTTP errors might be permanent
      if (error.response?.status === 404 || error.response?.status === 409) {
        permanentFailures.push({
          ...verification,
          failureReason: 'PERMANENT_ERROR',
          serverMessage: error.response?.data?.message,
        });
      } else {
        failedSyncs.push({
          ...verification,
          retryCount: retryCount + 1,
          lastAttemptAt: now.toISOString(),
          lastError: error.message,
        });
      }
    }
  }

  // Update queue with only retryable failures
  await storeOfflineQueue(failedSyncs);

  if (permanentFailures.length > 0) {
    await this.storePermanentFailures(permanentFailures);
  }

  return {
    success: true,
    syncedCount: syncResults.length,
    failedCount: failedSyncs.length,
    permanentFailureCount: permanentFailures.length,
  };
}

Data Synchronization

Unified Verification Approach

Support both online and offline operations seamlessly:

static async verifyCode(code, notes = "", isExit = false) {
  try {
    const isConnected = await this.isOnline();

    if (isConnected) {
      try {
        const endpoint = isExit ? "/codes/verify-exit" : "/codes/verify";
        const response = await api.post(endpoint, {
          code,
          notes,
          isExit,
        });

        // Background sync offline queue on successful online operation
        this.syncOfflineVerifications().catch((error) => {
          console.log("Background sync failed:", error);
        });

        return {
          success: true,
          data: response.data.data,
          verifiedOnline: true,
        };
      } catch (error) {
        // Fallback to offline only on network errors
        if (
          error.code === "NETWORK_ERROR" ||
          !error.response ||
          error.response.status >= 500
        ) {
          console.log("Falling back to offline verification");
          return await this.verifyCodeOffline(code, notes, isExit);
        }

        return {
          success: false,
          message: getErrorMessage(error),
        };
      }
    } else {
      return await this.verifyCodeOffline(code, notes, isExit);
    }
  } catch (error) {
    console.error("Verify code error:", error);
    return {
      success: false,
      message: "Failed to verify code",
    };
  }
}

Offline Data Verification

Implement local verification with state tracking:

static async verifyCodeOffline(inputCode, notes = "", isExit = false) {
  try {
    const { codes } = await getOfflineCodes();

    if (!codes || codes.length === 0) {
      return {
        success: false,
        message: "No offline codes available. Please sync when online.",
        needsSync: true,
      };
    }

    const cleanCode = inputCode.replace(/\s/g, "");
    const now = new Date();

    // Find matching code with proper state validation
    let matchingCode = codes.find((codeData) => {
      if (codeData.code !== cleanCode) return false;

      const isExpired = new Date(codeData.expiresAt) <= now;
      if (isExpired || codeData.isRevoked) return false;

      // Handle different code types and verification modes
      if (codeData.type === "regular") {
        if (isExit) {
          return (
            codeData.entryStatus === "entered" &&
            !codeData.exitVerified &&
            codeData.exitRequired
          );
        } else {
          return codeData.entryStatus === "pending" && !codeData.isUsed;
        }
      }

      // Additional type-specific logic...
      return false;
    });

    if (matchingCode) {
      const verificationId = `offline_${isExit ? "exit" : "entry"}_${Date.now()}`;

      // Update local state
      const updatedCodes = codes.map((code) =>
        code.code === cleanCode
          ? {
              ...code,
              isUsed: !isExit ? true : code.isUsed,
              usedAt: !isExit ? now.toISOString() : code.usedAt,
              exitVerified: isExit ? true : code.exitVerified,
              exitVerifiedAt: isExit ? now.toISOString() : code.exitVerifiedAt,
              entryStatus: isExit ? "exited" : "entered",
            }
          : code
      );

      await storeOfflineCodes(updatedCodes);

      // Add to sync queue
      await this.addToOfflineQueue({
        id: verificationId,
        code: cleanCode,
        codeId: matchingCode._id,
        notes,
        timestamp: now.toISOString(),
        verifiedOffline: true,
        synced: false,
        verificationType: isExit ? "exit" : "entry",
      });

      return {
        success: true,
        data: {
          ...matchingCode,
          verifiedOffline: true,
          verificationId,
        },
      };
    }

    return {
      success: false,
      message: "Invalid code or code not found.",
    };
  } catch (error) {
    console.error("Offline verify error:", error);
    return {
      success: false,
      message: "Failed to verify code offline",
    };
  }
}

Bidirectional Sync

Implement syncing in both directions - downloading fresh data and uploading queued operations:

static async syncCodesForOffline() {
  const isConnected = await this.isOnline();

  if (!isConnected) {
    return { success: false, message: "No internet connection" };
  }

  // First, sync offline verifications back to server
  const offlineSync = await this.syncOfflineVerifications();

  // Then download fresh codes
  const response = await api.get("/codes/sync");
  const codes = response.data.data.codes || [];

  // Preserve server state exactly
  const processedCodes = codes.map((code) => ({
    ...code,
    effectiveExpiresAt: code.effectiveExpiresAt || code.expiresAt,
    exitRequired: code.exitRequired !== undefined ? code.exitRequired : false,
    verifiedOffline: false,
    // Preserve critical state fields from server
    entryStatus: code.entryStatus,
    exitVerified: code.exitVerified,
    isUsed: code.isUsed,
    usedAt: code.usedAt,
  }));

  const syncTime = response.data.syncTime || new Date().toISOString();
  await storeOfflineCodes(processedCodes, syncTime);

  return {
    success: true,
    codesCount: processedCodes.length,
    syncTime,
    offlineVerificationsSynced: offlineSync.syncedCount || 0,
  };
}

Context-Based State Management

App-Wide Context

Create a central context for managing offline state:

export const AppProvider = ({ children }) => {
  const [state, dispatch] = useReducer(appReducer, initialState);
  const previousOnlineStatus = useRef(state.isOnline);
  const autoSyncTimeout = useRef(null);
  const isMounted = useRef(true);

  useEffect(() => {
    isMounted.current = true;

    const unsubscribe = NetInfo.addEventListener(networkState => {
      const isOnline = networkState.isConnected;
      const wasOffline = !previousOnlineStatus.current;

      dispatch({
        type: 'SET_ONLINE_STATUS',
        payload: isOnline
      });

      if (isOnline && wasOffline && state.settings.autoSync) {
        if (autoSyncTimeout.current) {
          clearTimeout(autoSyncTimeout.current);
        }

        autoSyncTimeout.current = setTimeout(() => {
          if (isMounted.current) {
            handleAutoSync();
          }
        }, 2000);
      }

      previousOnlineStatus.current = isOnline;
    });

    loadInitialData();

    return () => {
      isMounted.current = false;
      unsubscribe();
      if (autoSyncTimeout.current) {
        clearTimeout(autoSyncTimeout.current);
      }
    };
  }, []);

  const handleAutoSync = async () => {
    try {
      const result = await syncData();

      if (result.success) {
        dispatch({
          type: 'SET_LAST_AUTO_SYNC',
          payload: new Date().toISOString()
        });

        if (result.offlineVerificationsSynced > 0) {
          addNotification({
            type: 'success',
            title: 'Auto-Sync Complete',
            message: `${result.codesCount} codes synced, ${result.offlineVerificationsSynced} offline verifications uploaded`,
          });
        }
      }
    } catch (error) {
      console.error('Auto-sync error:', error);
    }
  };

  const syncData = async () => {
    if (!state.isOnline) {
      return { success: false, message: 'No internet connection' };
    }

    const result = await CodeService.syncCodesForOffline();

    if (result.success) {
      dispatch({
        type: 'SET_LAST_SYNC_TIME',
        payload: result.syncTime
      });
    }

    return result;
  };

  return (
    <AppContext.Provider value={{ ...state, syncData }}>
      {children}
    </AppContext.Provider>
  );
};

Feature-Specific Context

Create specialized contexts for different features:

export const CodeProvider = ({ children }) => {
  const { user } = useAuth();
  const [state, dispatch] = useReducer(codeReducer, initialState);

  useEffect(() => {
    if (user) {
      loadInitialData();
    }
  }, [user]);

  const syncCodes = useCallback(async () => {
    if (state.isSyncing) {
      return { success: false, message: "Sync already in progress" };
    }

    try {
      dispatch({ type: "SET_SYNCING", payload: true });

      const result = await CodeService.syncCodesForOffline();

      if (result.success) {
        dispatch({
          type: "SYNC_SUCCESS",
          payload: {
            codesCount: result.codesCount,
            syncTime: result.syncTime,
          },
        });
      }

      return result;
    } catch (error) {
      dispatch({ 
        type: "SET_SYNC_ERROR", 
        payload: "Failed to sync codes" 
      });
      return { success: false, message: error.message };
    }
  }, [state.isSyncing]);

  return (
    <CodeContext.Provider value={{ ...state, syncCodes }}>
      {children}
    </CodeContext.Provider>
  );
};

Handling Edge Cases

Stale Data Detection

Implement mechanisms to detect and handle stale offline data:

const MAX_AGE_HOURS = 72;

const isDataStale = (lastSyncTime) => {
  if (!lastSyncTime) return true;

  const now = new Date();
  const syncDate = new Date(lastSyncTime);
  const ageInHours = (now - syncDate) / (1000 * 60 * 60);

  return ageInHours > MAX_AGE_HOURS;
};

// In your UI
if (isDataStale(lastSyncTime)) {
  return (
    <View style={styles.staleDataWarning}>
      <Text>Your offline data is outdated. Please sync when online.</Text>
      <Button onPress={syncCodes} title="Sync Now" />
    </View>
  );
}

Conflict Resolution

Handle conflicts when offline changes conflict with server state:

static async resolveConflict(localData, serverData) {
  // Server-wins strategy for most cases
  if (serverData.updatedAt > localData.updatedAt) {
    return { resolved: serverData, strategy: 'server-wins' };
  }

  // Client-wins for specific fields
  const merged = {
    ...serverData,
    // Preserve local offline operations
    offlineOperations: localData.offlineOperations,
  };

  return { resolved: merged, strategy: 'merged' };
}

Cache Invalidation

Implement proper cache clearing:

const clearCacheAndRefresh = useCallback(async () => {
  try {
    // Clear all code-related state
    dispatch({ type: 'SET_ACTIVE_CODES', payload: { codes: [], count: 0 } });
    dispatch({ type: 'SET_LAST_SYNC_TIME', payload: null });
    dispatch({ type: 'CLEAR_SYNC_ERROR' });

    // Clear storage
    await clearOfflineCodes();
    await clearOfflineQueue();

    // Force reload
    setTimeout(() => {
      loadActiveCodes();
    }, 100);

    return { success: true };
  } catch (error) {
    return { success: false, error: error.message };
  }
}, [loadActiveCodes]);

Best Practices

1. Always Use Refs for Cleanup

Prevent memory leaks and race conditions:

const isMountedRef = useRef(true);
const timeoutRef = useRef(null);

useEffect(() => {
  return () => {
    isMountedRef.current = false;
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
  };
}, []);

// Use in async operations
const fetchData = async () => {
  const data = await api.get('/data');

  if (isMountedRef.current) {
    setState(data);
  }
};

2. Implement Progressive Loading

Load data incrementally to improve perceived performance:

const loadInitialData = async () => {
  // Load critical data first
  const essentialData = await getEssentialData();
  setEssentialData(essentialData);

  // Load secondary data
  setTimeout(async () => {
    const secondaryData = await getSecondaryData();
    setSecondaryData(secondaryData);
  }, 100);
};

3. Provide Clear User Feedback

Always inform users about offline state and sync status:

const OfflineSyncIndicator = () => {
  const { isOnline, isSyncing, lastSyncTime, pendingVerifications } = useApp();

  return (
    <TouchableOpacity onPress={handleManualSync}>
      <View style={styles.indicator}>
        <Icon name={getStatusIcon()} color={getStatusColor()} />
        <Text>{getStatusText()}</Text>
        {pendingVerifications > 0 && (
          <Badge count={pendingVerifications} />
        )}
      </View>
    </TouchableOpacity>
  );
};

4. Implement Exponential Backoff

Don't hammer the server with retry attempts:

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

5. Log Everything

Comprehensive logging helps debug offline issues:

const logOfflineOperation = (operation, data) => {
  console.log(`[OFFLINE] ${operation}:`, {
    timestamp: new Date().toISOString(),
    operation,
    data,
    queueLength: offlineQueue.length,
    networkStatus: isOnline ? 'online' : 'offline',
  });
};

6. Test Offline Scenarios

Always test these scenarios:

App starts offline
Connection lost during operation
Connection restored (immediate and delayed sync)
Multiple offline operations queued
Sync failures and retries
Data conflicts
Storage limits reached

7. Monitor Performance

Track storage usage and sync performance:

const monitorStorageUsage = async () => {
  const offlineCodes = await getOfflineCodes();
  const offlineQueue = await getOfflineQueue();

  const usage = {
    codesCount: offlineCodes.codes?.length || 0,
    queueLength: offlineQueue.length || 0,
    estimatedSize: estimateSize(offlineCodes) + estimateSize(offlineQueue),
  };

  console.log('Storage usage:', usage);

  if (usage.estimatedSize > 5 * 1024 * 1024) { // 5MB
    console.warn('Storage usage high, consider cleanup');
  }
};

Conclusion

Building robust offline functionality requires careful planning and implementation across multiple layers of your application. Key takeaways:

Design for offline-first: Assume users will be offline and make that the default experience
Implement intelligent syncing: Don't just dump data - handle conflicts, retries, and failures gracefully
Provide clear feedback: Users need to know what's happening with their data
Test thoroughly: Offline scenarios are complex and require extensive testing
Monitor and optimize: Track storage usage, sync performance, and user behavior

The patterns shown here have been battle-tested in a production visitor management system handling thousands of offline verifications. They can be adapted to any React Native application that needs to work offline.

Remember: great offline functionality is invisible to users - they just expect things to work, whether online or offline. Your job is to make that happen seamlessly.

Resources

Have questions or suggestions? Let me know in the comments below!

Converting Your Website to a PWA: A Comprehensive Guide

Oghenetega Adiri — Sun, 18 May 2025 11:20:04 +0000

Building web and mobile solutions has been my passion for years, but the moment I converted my first website into a Progressive Web App (PWA), I realized I had been missing out on a whole new dimension of user experience. As a senior developer based in Port Harcourt, Nigeria, where internet connectivity can sometimes be unreliable, I've seen firsthand how PWAs can transform user engagement by providing offline capabilities, faster load times, and native-like experiences.

In this guide, I'll walk you through the complete process of converting both traditional websites and framework-based applications into PWAs, sharing useful examples.

What are Progressive Web Apps?

Progressive Web Apps are web applications that use modern web capabilities to deliver app-like experiences to users. They work offline, can be installed on home screens, and provide features like push notifications—all without the friction of app store distribution.

Let me share why PWAs matter with a quick story: Last year, I worked with a local business here in Port Harcourt that was struggling with customer engagement. After converting their simple website to a PWA, they saw a 70% increase in return visitors and a significant uptick in sales, particularly during internet outages when competitors' websites were inaccessible.

Converting Traditional HTML/CSS/JavaScript Websites to PWAs

Step 1: Create a Web App Manifest

The manifest.json file tells browsers how your app should behave when installed. Here's a basic example I use for most of my HTML/CSS/JavaScript projects:

{
  "name": "TegaTech Solutions",
  "short_name": "TegaTech",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4A90E2",
  "description": "Building scalable solutions for Nigerian businesses",
  "icons": [
    {
      "src": "images/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Add this to your HTML:

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

Step 2: Add iOS Support

Apple devices require additional meta tags:

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="apple-mobile-web-app-title" content="TegaTech">
<link rel="apple-touch-icon" href="/images/icon-152.png">

Step 3: Implement a Service Worker

Service workers enable the offline capabilities that make PWAs so powerful. Here's a simplified version:

// service-worker.js
const CACHE_NAME = 'tegate-cache-v1';
const urlsToCache = [
  '/',
  '/index.html',
  '/css/styles.css',
  '/js/main.js',
  '/images/logo.png',
  // Add other assets you want to cache
];

// Installation - caches assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => {
        console.log('Cache opened successfully');
        return cache.addAll(urlsToCache);
      })
  );
});

// Fetch - serve from cache, fallback to network
self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(response => {
        // Return cached response if found
        if (response) {
          return response;
        }

        // Clone the request for the fetch call
        const fetchRequest = event.request.clone();

        return fetch(fetchRequest).then(response => {
          // Don't cache non-successful responses or non-GET requests
          if (!response || response.status !== 200 || response.type !== 'basic' || event.request.method !== 'GET') {
            return response;
          }

          // Clone the response for caching
          const responseToCache = response.clone();

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

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

// Activate - clean up old caches
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);
          }
        })
      );
    })
  );
});

// In your main.js or inline in HTML
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js')
      .then(registration => {
        console.log('ServiceWorker registered successfully:', registration.scope);
      })
      .catch(error => {
        console.log('ServiceWorker registration failed:', error);
      });
  });
}

Step 4: Implement "Add to Home Screen" Experience

I found that customizing the install experience significantly improves installation rates:

let deferredPrompt;

// Listen for the beforeinstallprompt event
window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67+ from automatically showing the prompt
  e.preventDefault();

  // Stash the event so it can be triggered later
  deferredPrompt = e;

  // Update UI to notify the user they can add to home screen
  const installBanner = document.getElementById('installBanner');
  if (installBanner) {
    installBanner.style.display = 'flex';
  }
});

// Setup the install button click handler
document.getElementById('installBtn').addEventListener('click', async () => {
  // Hide our user interface that shows our install button
  document.getElementById('installBanner').style.display = 'none';

  // Show the prompt
  deferredPrompt.prompt();

  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  console.log(`User response: ${outcome}`);

  // We've used the prompt, and can't use it again, throw it away
  deferredPrompt = null;
});

// Listen for successful installation
window.addEventListener('appinstalled', (event) => {
  console.log('App was installed to home screen');
  // Analytics tracking
  gtag('event', 'pwa_installed');
});

The corresponding HTML:

<div id="installBanner" class="install-banner" style="display: none;">
  <p>Install TegaTech for a better experience!</p>
  <button id="installBtn">Install Now</button>
  <button id="dismissBtn" onclick="this.parentNode.style.display='none'">Maybe Later</button>
</div>

And some CSS I typically use:

.install-banner {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  background: #f8f9fa;
  color: #333;
  padding: 16px;
  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.1);
  display: flex;
  justify-content: space-between;
  align-items: center;
  font-family: 'Segoe UI', sans-serif;
  z-index: 1000;
}

.install-banner button {
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-weight: bold;
}

#installBtn {
  background: #4A90E2;
  color: white;
}

#dismissBtn {
  background: transparent;
  color: #666;
}

Step 5: Test Your Traditional PWA

After implementing the above steps on a local business site, I always test using Lighthouse in Chrome DevTools:

Open Chrome DevTools (F12)
Go to the "Lighthouse" tab
Check "Progressive Web App" in the categories
Click "Generate report"

I've learned the hard way that fixing issues early saves a lot of headache later. For example, on a previous project, I found that some assets weren't being cached correctly, which was causing the PWA to work inconsistently offline.

Converting React and Vue Applications to PWAs

Framework-based applications follow similar principles but with some framework-specific approaches.

React Implementation

For React applications, I typically use Create React App (CRA) which has built-in PWA support:

If starting a new project:

npx create-react-app my-pwa --template cra-template-pwa

For existing projects, add PWA support:

npm install workbox-webpack-plugin --save-dev

In your src/index.js, modify the service worker registration:

// Before React 18
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorkerRegistration from './serviceWorkerRegistration';

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note: this comes with some pitfalls.
// Learn more about service workers: https://cra.link/PWA
serviceWorkerRegistration.register();

Customize the manifest.json in the public folder:

{
  "short_name": "NigerTech",
  "name": "Nigerian Tech Solutions by Adiri",
  "icons": [
    {
      "src": "favicon.ico",
      "sizes": "64x64",
      "type": "image/x-icon"
    },
    {
      "src": "logo192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "logo512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff"
}

For custom "Add to Home Screen" prompts in React, I create a reusable component:

import React, { useState, useEffect } from 'react';
import './InstallPrompt.css';

const InstallPrompt = () => {
  const [installPrompt, setInstallPrompt] = useState(null);
  const [showBanner, setShowBanner] = useState(false);

  useEffect(() => {
    window.addEventListener('beforeinstallprompt', (e) => {
      // Prevent the mini-infobar from appearing on mobile
      e.preventDefault();
      // Stash the event so it can be triggered later
      setInstallPrompt(e);
      // Check if user has engaged enough with the app
      if (hasUserEngagedEnough()) {
        setShowBanner(true);
      }
    });

    window.addEventListener('appinstalled', () => {
      // Log install to analytics
      console.log('PWA was installed');
      setShowBanner(false);
    });

    return () => {
      window.removeEventListener('beforeinstallprompt', () => {});
      window.removeEventListener('appinstalled', () => {});
    };
  }, []);

  const hasUserEngagedEnough = () => {
    // For simplicity, we're just checking if they've visited before
    return localStorage.getItem('visited') === 'true';
  };

  const handleInstallClick = async () => {
    if (!installPrompt) return;

    // Show the install prompt
    installPrompt.prompt();

    // Wait for the user to respond to the prompt
    const { outcome } = await installPrompt.userChoice;
    console.log(`User response to the install prompt: ${outcome}`);

    // We've used the prompt, and can't use it again
    setInstallPrompt(null);
    setShowBanner(false);
  };

  const handleDismiss = () => {
    setShowBanner(false);
    // Remember dismissal in localStorage
    localStorage.setItem('installPromptDismissed', Date.now().toString());
  };

  if (!showBanner) return null;

  return (
    <div className="install-banner">
      <p>Get the best experience with our app!</p>
      <div className="banner-buttons">
        <button onClick={handleInstallClick} className="install-btn">
          Install Now
        </button>
        <button onClick={handleDismiss} className="dismiss-btn">
          Not Now
        </button>
      </div>
    </div>
  );
};

export default InstallPrompt;

I then include this component in my App.js:

import React, { useEffect } from 'react';
import InstallPrompt from './components/InstallPrompt';
import './App.css';

function App() {
  useEffect(() => {
    // Mark that user has visited the site
    localStorage.setItem('visited', 'true');
  }, []);

  return (
    <div className="App">
      <header className="App-header">
        <h1>TegaTech Solutions</h1>
        <p>Building the future, one app at a time</p>
      </header>
      <main>
        {/* Your app content */}
      </main>
      <InstallPrompt />
    </div>
  );
}

export default App;

Vue Implementation

For Vue.js projects, I use the PWA plugin:

For new projects:

vue create my-pwa
cd my-pwa
vue add pwa

For existing projects:

vue add pwa

After adding the plugin, you can customize the PWA settings in the vue.config.js file:

// vue.config.js
module.exports = {
  pwa: {
    name: 'TegaTech App',
    themeColor: '#4A90E2',
    msTileColor: '#000000',
    appleMobileWebAppCapable: 'yes',
    appleMobileWebAppStatusBarStyle: 'black',
    workboxPluginMode: 'GenerateSW',
    workboxOptions: {
      skipWaiting: true,
      clientsClaim: true,
      exclude: [/\.map$/, /_redirects/],
      runtimeCaching: [
        {
          urlPattern: new RegExp('^https://api\\.myapp\\.com/'),
          handler: 'NetworkFirst',
          options: {
            cacheName: 'api-cache',
            expiration: {
              maxEntries: 50,
              maxAgeSeconds: 60 * 60 * 24, // 1 day
            },
          },
        },
        {
          urlPattern: new RegExp('^https://fonts\\.googleapis\\.com/'),
          handler: 'StaleWhileRevalidate',
          options: {
            cacheName: 'google-fonts-stylesheets',
          },
        },
      ],
    },
    iconPaths: {
      favicon32: 'img/icons/favicon-32x32.png',
      favicon16: 'img/icons/favicon-16x16.png',
      appleTouchIcon: 'img/icons/apple-touch-icon.png',
      maskIcon: 'img/icons/safari-pinned-tab.svg',
      msTileImage: 'img/icons/mstile-150x150.png'
    }
  }
}

Create a custom install component in Vue:

<!-- InstallPrompt.vue -->
<template>
  <div v-if="showBanner" class="install-banner">
    <p>Install our app for the best experience in Port Harcourt!</p>
    <div class="banner-buttons">
      <button @click="handleInstall" class="install-btn">Install</button>
      <button @click="handleDismiss" class="dismiss-btn">Not Now</button>
    </div>
  </div>
</template>

<script>
export default {
  name: 'InstallPrompt',
  data() {
    return {
      deferredPrompt: null,
      showBanner: false
    }
  },
  mounted() {
    window.addEventListener('beforeinstallprompt', (e) => {
      e.preventDefault();
      this.deferredPrompt = e;

      // Check if user should see the banner
      if (this.hasUserEngaged()) {
        this.showBanner = true;
      }
    });

    window.addEventListener('appinstalled', () => {
      console.log('App installed successfully');
      this.showBanner = false;
      this.$emit('app-installed');
    });
  },
  methods: {
    hasUserEngaged() {
      // Simple engagement check
      return localStorage.getItem('pageVisits') >= 2;
    },
    async handleInstall() {
      if (!this.deferredPrompt) return;

      this.deferredPrompt.prompt();
      const { outcome } = await this.deferredPrompt.userChoice;

      console.log(`Installation outcome: ${outcome}`);
      this.deferredPrompt = null;
      this.showBanner = false;
    },
    handleDismiss() {
      this.showBanner = false;
      localStorage.setItem('installDismissed', Date.now().toString());
    }
  },
  beforeDestroy() {
    window.removeEventListener('beforeinstallprompt', () => {});
    window.removeEventListener('appinstalled', () => {});
  }
}
</script>

<style scoped>
.install-banner {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  background: #f8f9fa;
  padding: 16px;
  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.1);
  display: flex;
  justify-content: space-between;
  align-items: center;
  z-index: 1000;
}

.banner-buttons {
  display: flex;
  gap: 10px;
}

.install-btn {
  padding: 8px 16px;
  background: #4A90E2;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.dismiss-btn {
  padding: 8px 16px;
  background: transparent;
  color: #666;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

Use this component in your App.vue:

<template>
  <div id="app">
    <!-- Your app content -->
    <InstallPrompt @app-installed="trackInstallation" />
  </div>
</template>

<script>
import InstallPrompt from './components/InstallPrompt.vue';

export default {
  name: 'App',
  components: {
    InstallPrompt
  },
  mounted() {
    // Track page visits for engagement metrics
    const visits = parseInt(localStorage.getItem('pageVisits') || '0');
    localStorage.setItem('pageVisits', visits + 1);
  },
  methods: {
    trackInstallation() {
      // Track installation in analytics
      console.log('App installed by user');
    }
  }
}
</script>

Best Practices I've Learned Along the Way

After implementing PWAs for various clients , I've gathered some valuable insights:

Start with Lighthouse: Always use Lighthouse to audit your PWA before and after implementation. It's saved me countless debugging hours.
Optimize the Install Experience: I've found that showing the install prompt after users have engaged with your content (e.g., visited 2+ pages) increases installation rates by over 30%.
Test on Real Devices: Last year, I spent days debugging a PWA that worked perfectly on my development machine but failed on actual smartphones. Now I always test on at least 3 different devices with varying connection speeds.
Use Push Notifications Sparingly: In one project, excessive notifications drove users away. Now I follow a rule: only send notifications that provide immediate value.
Implement Offline Feedback: Let users know when they're offline and what features are available. I built a simple offline banner component that has become standard in all my PWAs:

// Check for online/offline status
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);

function updateOnlineStatus() {
  const offlineBanner = document.getElementById('offline-banner');
  if (navigator.onLine) {
    offlineBanner.style.display = 'none';
  } else {
    offlineBanner.style.display = 'block';
  }
}

// Call on initial load
document.addEventListener('DOMContentLoaded', updateOnlineStatus);

Conclusion

Converting your website to a PWA isn't just following a technical checklist, it's about understanding your users' needs and creating an experience that works for them regardless of their network conditions or devices.

Here in Nigeria, where connectivity can be challenging and data costs are significant, PWAs have been game-changers for the businesses I work with. They've allowed my clients to reach users who otherwise might not be able to access their services reliably.

Whether you're working with a simple HTML site or a complex React application, the journey to PWA implementation follows similar principles. The key is to start small, test thoroughly, and continuously improve based on real user feedback.

Have you implemented a PWA for your website? What challenges did you face? I'd love to hear about your experiences in the comments!

IndexedDB vs localStorage: When to Use Which?

Oghenetega Adiri — Sun, 11 May 2025 17:43:42 +0000

Hey fellow developers! Ever found yourself wondering whether to use localStorage or IndexedDB for your web app's data storage needs? You're not alone! Let's dive into both options and figure out when each one shines. I promise to keep this practical and skip the boring parts. 😉

The TL;DR Version

localStorage: Simple, synchronous, perfect for small data (strings only)
IndexedDB: Complex, asynchronous, handles large data like a boss

Now let's get into the good stuff!

localStorage: The Simple One 📦

localStorage is like that reliable friend who's always there when you need them - straightforward, no-frills, gets the job done.

Quick Facts:

Stores key-value pairs as strings
Synchronous API (blocks your code)
~5-10MB storage limit (browser dependent)
Data persists until manually cleared

How to Use localStorage

// Storing data
localStorage.setItem('username', 'adiriTega');
localStorage.setItem('theme', 'dark');

// Storing objects (need to stringify first!)
const userSettings = {
  theme: 'dark',
  notifications: true,
  language: 'en'
};
localStorage.setItem('settings', JSON.stringify(userSettings));

// Retrieving data
const username = localStorage.getItem('username');
const settings = JSON.parse(localStorage.getItem('settings'));

// Removing items
localStorage.removeItem('username');

// Clear everything (nuclear option!)
localStorage.clear();

LocalStorage Pro Tips 💡

Always handle errors:

try {
  localStorage.setItem('key', 'value');
} catch (error) {
  console.error('Storage failed:', error);
  // Maybe the user is in private mode or storage is full
}

Create a wrapper for objects:

const storage = {
  set: (key, value) => {
    try {
      localStorage.setItem(key, JSON.stringify(value));
      return true;
    } catch (error) {
      console.error('Failed to save:', error);
      return false;
    }
  },

  get: (key, defaultValue = null) => {
    try {
      const item = localStorage.getItem(key);
      return item ? JSON.parse(item) : defaultValue;
    } catch (error) {
      console.error('Failed to get:', error);
      return defaultValue;
    }
  }
};

// Usage
storage.set('user', { name: 'John', age: 30 });
const user = storage.get('user', {});

IndexedDB: The Powerhouse 💪

IndexedDB is like that overachiever friend who can handle anything you throw at them. More complex? Sure. More powerful? Absolutely!

Quick Facts:

Stores any JavaScript data type
Asynchronous API (non-blocking)
Much larger storage capacity (often hundreds of MB)
Supports transactions, indexes, and queries

How to Use IndexedDB

Let's build a simple task manager to see IndexedDB in action:

// Initialize database
function initDB() {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open('TaskManager', 1);

    request.onerror = () => reject(request.error);
    request.onsuccess = () => resolve(request.result);

    request.onupgradeneeded = (event) => {
      const db = event.target.result;

      // Create object store
      const store = db.createObjectStore('tasks', { 
        keyPath: 'id', 
        autoIncrement: true 
      });

      // Create indexes
      store.createIndex('status', 'status', { unique: false });
      store.createIndex('priority', 'priority', { unique: false });
    };
  });
}

// Add a task
async function addTask(task) {
  const db = await initDB();

  return new Promise((resolve, reject) => {
    const transaction = db.transaction(['tasks'], 'readwrite');
    const store = transaction.objectStore('tasks');
    const request = store.add(task);

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

// Get all tasks
async function getAllTasks() {
  const db = await initDB();

  return new Promise((resolve, reject) => {
    const transaction = db.transaction(['tasks'], 'readonly');
    const store = transaction.objectStore('tasks');
    const request = store.getAll();

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

// Usage
async function demo() {
  try {
    // Add a new task
    await addTask({
      title: 'Learn IndexedDB',
      status: 'pending',
      priority: 'high',
      dueDate: new Date('2025-06-01')
    });

    // Get all tasks
    const tasks = await getAllTasks();
    console.log('All tasks:', tasks);
  } catch (error) {
    console.error('Error:', error);
  }
}

Modern IndexedDB with Promises

The callback-heavy API can be quite painful to implement. Here's a cleaner approach:

class TaskDB {
  constructor() {
    this.dbPromise = null;
  }

  async getDB() {
    if (!this.dbPromise) {
      this.dbPromise = this.openDB();
    }
    return this.dbPromise;
  }

  openDB() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open('TaskManager', 1);
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);

      request.onupgradeneeded = (event) => {
        const db = event.target.result;
        if (!db.objectStoreNames.contains('tasks')) {
          const store = db.createObjectStore('tasks', { 
            keyPath: 'id', 
            autoIncrement: true 
          });
          store.createIndex('status', 'status');
        }
      };
    });
  }

  async add(task) {
    const db = await this.getDB();
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['tasks'], 'readwrite');
      const store = transaction.objectStore('tasks');
      const request = store.add(task);
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }

  async getByStatus(status) {
    const db = await this.getDB();
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['tasks'], 'readonly');
      const store = transaction.objectStore('tasks');
      const index = store.index('status');
      const request = index.getAll(status);
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }
}

// Usage
const taskDB = new TaskDB();
taskDB.add({ title: 'Build awesome app', status: 'pending' });

The Ultimate Comparison 🥊

Feature	localStorage	IndexedDB
Simplicity	🟢 Super simple	🔴 More complex
Performance	🔴 Synchronous (blocking)	🟢 Asynchronous
Storage Capacity	🔴 5-10MB typical	🟢 Much larger
Data Types	🔴 Strings only	🟢 Any JS type
Querying	🔴 Key-only	🟢 Indexes & queries
Transactions	🔴 No	🟢 Yes
Browser Support	🟢 Excellent	🟢 Good (not IE)

When to Use What? 🤔

Use localStorage when:

Storing simple key-value pairs
Data size is small (< 5MB)
You need quick, synchronous access
Storing user preferences, tokens, or simple settings

Use IndexedDB when:

Storing complex data structures
Working with large datasets
Need offline data storage
Building complex queries
Creating offline-first applications

Real-World Examples

localStorage: User Preferences

const preferences = {
  saveUserPreferences(prefs) {
    localStorage.setItem('userPrefs', JSON.stringify(prefs));
  },

  getUserPreferences() {
    const prefs = localStorage.getItem('userPrefs');
    return prefs ? JSON.parse(prefs) : {
      theme: 'light',
      language: 'en',
      notifications: true
    };
  }
};

IndexedDB: Offline-First Todo App

class OfflineTodoApp {
  constructor() {
    this.dbPromise = this.initDB();
  }

  async initDB() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open('TodoApp', 1);

      request.onupgradeneeded = (event) => {
        const db = event.target.result;
        const store = db.createObjectStore('todos', { 
          keyPath: 'id',
          autoIncrement: true 
        });

        store.createIndex('completed', 'completed');
        store.createIndex('category', 'category');
      };

      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }

  async addTodo(todo) {
    const db = await this.dbPromise;
    const transaction = db.transaction(['todos'], 'readwrite');
    const store = transaction.objectStore('todos');

    return new Promise((resolve, reject) => {
      const request = store.add({
        ...todo,
        createdAt: Date.now(),
        synced: false // For later syncing with server
      });

      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }

  async toggleComplete(id) {
    const db = await this.dbPromise;
    const transaction = db.transaction(['todos'], 'readwrite');
    const store = transaction.objectStore('todos');

    const todo = await new Promise((resolve) => {
      const request = store.get(id);
      request.onsuccess = () => resolve(request.result);
    });

    if (todo) {
      todo.completed = !todo.completed;
      todo.synced = false;

      return new Promise((resolve, reject) => {
        const request = store.put(todo);
        request.onsuccess = () => resolve(request.result);
        request.onerror = () => reject(request.error);
      });
    }
  }
}

Pro Tips for Both

Always handle quota exceeded errors:

try {
  // Your storage code
} catch (error) {
  if (error.name === 'QuotaExceededError') {
    // Handle storage full scenario
    alert('Storage is full! Please clear some data.');
  }
}

Implement fallbacks:

const storage = {
  isAvailable() {
    try {
      const test = '__test__';
      localStorage.setItem(test, test);
      localStorage.removeItem(test);
      return true;
    } catch (e) {
      return false;
    }
  },

  set(key, value) {
    if (this.isAvailable()) {
      localStorage.setItem(key, JSON.stringify(value));
    } else {
      // Fallback to cookies or send to server
    }
  }
};

Consider using libraries:
- Dexie.js for IndexedDB
- localForage for unified API

Conclusion 🎉

Both localStorage and IndexedDB have their place in modern web development. localStorage is perfect for simple data storage, while IndexedDB shines when you need power and flexibility.

The key is understanding your needs:

Small, simple data? Go with localStorage.
Complex, large-scale data? IndexedDB is your friend.

Remember, the best storage solution is the one that fits your specific use case. Don't use a sledgehammer to kill an ant!

Happy coding.

What's your experience with browser storage? Drop a comment below and share your favorite tips and tricks

Real-Time Private Channel Notifications in Vue 3 with Laravel Echo and Pusher

Oghenetega Adiri — Sun, 04 May 2025 13:03:06 +0000

In today's fast-paced web applications, real-time notifications have become essential for providing users with immediate updates and enhancing their overall experience. In this comprehensive guide, I'll walk you through creating a real-time notification system using Vue 3's Composition API, Laravel Echo, and Pusher.

The implementation we'll cover includes a complete notification system with features like:

Connection management with automatic reconnection
Persistent subscriptions that survive page refreshes
Notification state management
Elegant UI components for displaying notifications
Browser notifications support

Prerequisites
Understanding the Architecture
Setting Up Laravel Echo
Creating a Notification Service
Building the Notification Store
UI Components for Notifications
Integrating with Authentication
Testing and Debugging
Best Practices
Conclusion

Prerequisites

Before we start building, you'll need:

A Vue 3 project using Composition API
A Laravel backend with Laravel Reverb and Laravel Echo Server set up
Basic knowledge of WebSockets and event broadcasting

Once you have all of the above, we can start digging in 😎👌🔥

Understanding the Architecture

Our notification system follows a layered architecture:

Laravel Echo Client: Core WebSocket connection manager
Notification Service: Business logic for handling notifications
Notification Store: State management for notifications
UI Components: Visual presentation of notifications

Each layer has a specific responsibility, making the system maintainable and extensible.

Setting Up Laravel Echo

Let's start by creating a dedicated Echo service that manages the WebSocket connections. This service will handle connection state persistence, automatic reconnection, and channel subscriptions.

// echo.js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

// LocalStorage keys for persistence
const ECHO_CONNECTION_ID = 'user_echo_connection_id';
const ECHO_CONNECTION_STATE = 'user_echo_connection_state';
const ECHO_SUBSCRIBED_CHANNELS = 'user_echo_subscribed_channels';
const ECHO_CHANNEL_HANDLERS = 'user_echo_channel_handlers';
const ECHO_LAST_ACTIVE = 'user_echo_last_active';

// Singleton instance
let echoInstance = null;

const createEcho = () => {
  const token = localStorage.getItem('token');
  const lastActive = localStorage.getItem(ECHO_LAST_ACTIVE);
  const timeElapsed = lastActive ? Date.now() - parseInt(lastActive) : null;

  // Update last active time
  localStorage.setItem(ECHO_LAST_ACTIVE, Date.now().toString());

  // Reuse existing connection if active
  if (echoInstance && 
      echoInstance.connector && 
      echoInstance.connector.pusher && 
      echoInstance.connector.pusher.connection.state === 'connected') {
    console.log('Reusing existing Echo instance with active connection');
    return echoInstance;
  }

  // Create new Echo instance
  echoInstance = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_REVERB_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT,
    forceTLS: import.meta.env.MODE === 'production' ? import.meta.env.VITE_REVERB_SCHEME : false,
    disableStats: true,
    enabledTransports: ['ws', 'wss'],
    cluster: 'mt1', //we are using a dummy cluster
    activityTimeout: 30000,
    pongTimeout: 15000,
    enableLogging: true,

    // Required for private channels
    authEndpoint: 'https://api.example.com/broadcasting/auth',  

    auth: {
      headers: {
        'X-APP-AUTH': import.meta.env.VITE_AUTH_KEY,
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
      }
    }
  });

  // Connection event handlers
  echoInstance.connector.pusher.connection.bind('connected', () => {
    const socketId = echoInstance.connector.pusher.connection.socket_id;
    localStorage.setItem(ECHO_CONNECTION_ID, socketId);
    localStorage.setItem(ECHO_CONNECTION_STATE, 'connected');
    localStorage.setItem(ECHO_LAST_ACTIVE, Date.now().toString());

    // Automatic resubscription to saved channels
    resubscribeToSavedChannels();
  });

  // Add more connection event handlers...
  echoInstance.connector.pusher.connection.bind('disconnected', () => {
    localStorage.setItem(ECHO_CONNECTION_STATE, 'disconnected');
  });

  echoInstance.connector.pusher.connection.bind('error', (err) => {
    console.error('Pusher connection error:', err);
  });

  // Track subscriptions for persistence
  echoInstance.saveSubscription = (channelName, eventName, handlerInfo) => {
    try {
      // Get current subscriptions
      const subscribedChannels = JSON.parse(localStorage.getItem(ECHO_SUBSCRIBED_CHANNELS) || '[]');
      if (!subscribedChannels.includes(channelName)) {
        subscribedChannels.push(channelName);
        localStorage.setItem(ECHO_SUBSCRIBED_CHANNELS, JSON.stringify(subscribedChannels));
      }

      // Save event handlers
      const handlers = JSON.parse(localStorage.getItem(ECHO_CHANNEL_HANDLERS) || '{}');
      if (!handlers[channelName]) {
        handlers[channelName] = [];
      }

      // Check for duplicate handlers
      const existingHandler = handlers[channelName].find(h => h.event === eventName);
      if (!existingHandler) {
        handlers[channelName].push({
          event: eventName,
          type: handlerInfo.type
        });
        localStorage.setItem(ECHO_CHANNEL_HANDLERS, JSON.stringify(handlers));
      }
    } catch (error) {
      console.error('Error saving subscription:', error);
    }
  };

  // Handle visibility changes to reconnect when tab becomes active
  document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'visible') {
      const pusher = echoInstance?.connector?.pusher;
      if (pusher && pusher.connection.state !== 'connected') {
        console.log('Page visible, reconnecting...');
        pusher.connect();
      }
    }
  });

  return echoInstance;
};

// Function to resubscribe to saved channels
function resubscribeToSavedChannels() {
  try {
    const subscribedChannels = JSON.parse(localStorage.getItem(ECHO_SUBSCRIBED_CHANNELS) || '[]');
    const handlers = JSON.parse(localStorage.getItem(ECHO_CHANNEL_HANDLERS) || '{}');

    if (subscribedChannels.length === 0) return;

    // Trigger resubscription via global handler
    if (window.userResubscribeToChannels) {
      window.userResubscribeToChannels(subscribedChannels, handlers);
    }
  } catch (error) {
    console.error('Error during resubscription:', error);
  }
}

// Clear Echo state on logout
createEcho.clearEchoState = () => {
  localStorage.removeItem(ECHO_SUBSCRIBED_CHANNELS);
  localStorage.removeItem(ECHO_CHANNEL_HANDLERS);
  localStorage.removeItem(ECHO_CONNECTION_ID);
  localStorage.removeItem(ECHO_CONNECTION_STATE); 
  localStorage.removeItem(ECHO_LAST_ACTIVE);

  // Disconnect instance if exists
  if (echoInstance && echoInstance.connector) {
    try {
      echoInstance.connector.pusher.disconnect();
    } catch (e) {
      console.error('Error disconnecting Echo:', e);
    }
    echoInstance = null;
  }
};

// For debugging
window.userEchoDebug = {
  getInstance: () => echoInstance,
  getConnectionState: () => echoInstance?.connector?.pusher?.connection?.state || 'no-instance',
  clearState: createEcho.clearEchoState,
  getStoredState: () => ({
    connectionId: localStorage.getItem(ECHO_CONNECTION_ID),
    connectionState: localStorage.getItem(ECHO_CONNECTION_STATE),
    channels: JSON.parse(localStorage.getItem(ECHO_SUBSCRIBED_CHANNELS) || '[]'),
    handlers: JSON.parse(localStorage.getItem(ECHO_CHANNEL_HANDLERS) || '{}'),
    lastActive: localStorage.getItem(ECHO_LAST_ACTIVE)
  })
};

export default createEcho;

Our createEcho.js module provides several key features:

Singleton pattern - Only one Echo instance is created
Connection state persistence - Saves connection state in localStorage
Channel subscription persistence - Tracks subscribed channels
Automatic reconnection - Reconnects when the page becomes visible
Debugging tools - Global object for connection debugging

Creating a Notification Service

Next, let's create a notification service that uses our Echo instance to subscribe to notification channels and format incoming notifications:

// notificationService.js
import { ref } from "vue";
import createEcho from "./echo";
import { useNotificationStore } from "@/stores/notificationStore";

// Initialization key
const USER_NOTIFICATION_INIT_KEY = 'user_notification_service_initialized';

export const useNotificationService = async (providedUserStore = null) => {
  // Create a fresh Echo instance with the current token
  const echo = createEcho();

  // Get user store (passed or dynamically imported)
  const userStore = providedUserStore || (await getUserStore());

  // Initialize notification store
  const notificationStore = useNotificationStore();

  // Notification type constants
  const notificationTypes = {
    TRIP_CREATED: "trip_created",
    WALLET_FUNDED: "wallet_funded",
    // Add more notification types...
  };

  // Format notification based on type and data
  const formatNotification = (type, data) => {
    const currentTime = new Date();
    const formattedTime = currentTime.toLocaleTimeString([], {
      hour: "2-digit",
      minute: "2-digit",
    });
    const formattedDate = currentTime.toLocaleDateString("en-US", {
      month: "long",
      day: "numeric",
      year: "numeric",
    });

    let message = "";
    let title = "";

    // Format notification based on type
    switch (type) {
      case notificationTypes.TRIP_CREATED:
        title = "Trip Created";
        message = data.message;
        break;
      case notificationTypes.WALLET_FUNDED:
        title = "Wallet Funded";
        message = data.message;
        break;
      // Add more notification types...
      default:
        title = "Notification";
        message = "You have a new notification";
    }

    return {
      id: Date.now(),
      type,
      title,
      message,
      time: formattedTime,
      date: formattedDate,
      fullTime: `${formattedDate} . ${formattedTime}`,
      data,
      status: "unread",
    };
  };

  // Add notification to store and show browser notification
  const addNotification = (notification) => {
    // Add to global notification store
    notificationStore.addNotification(notification);

    // Show browser notification if allowed
    if (Notification.permission === "granted") {
      try {
        new Notification(notification.title, {
          body: notification.message,
          icon: "/favicon.png",
        });
      } catch (error) {
        console.warn("Error displaying browser notification:", error);
      }
    }
  };

  // Helper to get user store dynamically (avoids circular dependency)
  const getUserStore = async () => {
    const { useUserStore } = await import("@/stores/userStore");
    return useUserStore();
  };

  // Subscribe to a private channel with error handling
  const subscribeToPrivateChannel = (channelName, eventName, handler, handlerType) => {
    try {
      // Check if channel already exists
      const existingChannels = echo.connector.pusher.channels.channels;
      if (existingChannels[channelName]) {
        existingChannels[channelName].bind(eventName, handler);
        return existingChannels[channelName];
      }

      // Create new subscription
      const channel = echo.private(channelName);

      // Debug subscription status
      channel.subscribed(() => {
        console.log(`Successfully subscribed to private channel: ${channelName}`);

        // Track this subscription with its handler info
        echo.saveSubscription(channelName, eventName, { type: handlerType });
      });

      // Error handler
      channel.error((err) => {
        console.error(`Channel subscription error for ${channelName}:`, err);
      });

      // Bind the event handler
      channel.listen(eventName, (data) => {
        console.log(`Received event ${eventName} on channel ${channelName}:`, data);
        handler(data);
      });

      return channel;
    } catch (error) {
      console.error(`Exception when subscribing to private channel ${channelName}:`, error);
      return null;
    }
  };

  // Global resubscription handler for saved channels
  window.userResubscribeToChannels = (channels, handlers) => {
    if (!userStore.user?.id) {
      console.error("User ID not available for resubscription");
      return;
    }

    const userId = userStore.user.id;

    channels.forEach(channelName => {
      const channelHandlers = handlers[channelName] || [];

      // Resubscribe based on saved handlers
      channelHandlers.forEach(handlerInfo => {
        // Create appropriate event handlers based on channel and event
        if (channelName === `trip.created.${userId}` && handlerInfo.event === 'TripCreated') {
          subscribeToPrivateChannel(
            channelName,
            handlerInfo.event,
            (data) => {
              const notification = formatNotification(notificationTypes.TRIP_CREATED, data);
              addNotification(notification);
            },
            'TRIP_CREATED'
          );
        } 
        // Add more channel/event combinations...
      });

      // If no handlers found, create based on channel name pattern
      if (!channelHandlers.length) {
        if (channelName === `trip.created.${userId}`) {
          subscribeToPrivateChannel(
            channelName,
            "TripCreated",
            (data) => {
              const notification = formatNotification(notificationTypes.TRIP_CREATED, data);
              addNotification(notification);
            },
            'TRIP_CREATED'
          );
        } 
        // Add more channel patterns...
      }
    });
  };

  // Initialize Echo and subscribe to channels
  const initializeEcho = async () => {
    if (!userStore.user?.id) {
      console.error("User ID not available for notification subscription");
      return;
    }

    const userId = userStore.user.id;
    console.log(`Initializing notifications for user ID: ${userId}`);

    // Mark service as initialized
    localStorage.setItem(USER_NOTIFICATION_INIT_KEY, 'true');

    // Subscribe to user-specific channels
    subscribeToPrivateChannel(
      `trip.created.${userId}`,
      "TripCreated",
      (data) => {
        const notification = formatNotification(notificationTypes.TRIP_CREATED, data);
        addNotification(notification);
      },
      'TRIP_CREATED'
    );

    // Add more channel subscriptions...

    // Subscribe to trip-specific channels if needed
    subscribeToTripChannels();
  };

  // Subscribe to trip-specific channels
  const subscribeToTripChannels = async () => {
    // Get user's active trips
    const userTrips = userStore.activeTrips || [];

    if (userTrips.length === 0) {
      console.log("No active trips found for subscription");
      return;
    }

    // Subscribe to channels for each trip
    userTrips.forEach((trip) => {
      const tripId = trip;

      // Add trip-specific subscriptions...
      subscribeToPrivateChannel(
        `trip.departure.${tripId}`,
        "TripDeparture", 
        (data) => {
          const notification = formatNotification(
            notificationTypes.TRIP_DEPARTURE,
            {
              ...data,
              departure: trip.departure,
              destination: trip.destination,
            }
          );
          addNotification(notification);
        },
        'TRIP_DEPARTURE'
      );

      // Add more trip-specific channels...
    });
  };

  // Request browser notification permission
  const requestNotificationPermission = async () => {
    if (!("Notification" in window)) {
      console.log("This browser does not support desktop notifications");
      return false;
    }

    if (Notification.permission === "granted") {
      return true;
    }

    if (Notification.permission !== "denied") {
      const permission = await Notification.requestPermission();
      return permission === "granted";
    }

    return false;
  };

  // Cleanup function for logout
  const cleanup = () => {
    try {
      console.log("Cleaning up user notification subscriptions...");

      // Use the clearEchoState method to remove localStorage entries
      createEcho.clearEchoState();

      // Remove global resubscribe handler
      delete window.userResubscribeToChannels;

      // Remove the notification initialization flag
      localStorage.removeItem(USER_NOTIFICATION_INIT_KEY);

      // Clear the notification store
      notificationStore.deleteAllNotifications();

      console.log('User notification service cleaned up');
    } catch (error) {
      console.error("Error cleaning up user notifications:", error);
    }
  };

  // Return service methods and state
  return {
    // Get notifications from store
    get notifications() {
      return {
        value: notificationStore.notifications
      };
    },
    get unreadCount() {
      return {
        value: notificationStore.unreadCount
      };
    },
    initializeEcho,
    markAllAsRead: notificationStore.markAllAsRead,
    markAsRead: notificationStore.markAsRead,
    subscribeToTripChannels,
    requestNotificationPermission,
    cleanup,
  };
};

export default useNotificationService;

The notification service:

Creates an Echo instance for WebSocket connection
Provides formatting for different notification types
Manages channel subscriptions and resubscriptions
Handles browser notification permissions
Offers cleanup functionality for logout

Building the Notification Store

To manage notification state across components, we need a store. In a Vue 3 project, you can use Pinia or a similar state management solution:

// notificationStore.js
import { defineStore } from 'pinia';

export const useNotificationStore = defineStore('notification', {
  state: () => ({
    notifications: [],
  }),

  getters: {
    // Get unread count
    unreadCount: (state) => state.notifications.filter(n => n.status === 'unread').length,

    // Get notifications by status
    getNotificationsByStatus: (state) => (status) => {
      return state.notifications.filter(notification => notification.status === status);
    },
  },

  actions: {
    // Add a new notification
    addNotification(notification) {
      this.notifications.unshift(notification);
    },

    // Mark notification as read
    markAsRead(notificationId) {
      const notification = this.notifications.find(n => n.id === notificationId);
      if (notification) {
        notification.status = 'read';
      }
    },

    // Mark all notifications as read
    markAllAsRead() {
      this.notifications.forEach(notification => {
        notification.status = 'read';
      });
    },

    // Delete a notification
    deleteNotification(notificationId) {
      const index = this.notifications.findIndex(n => n.id === notificationId);
      if (index !== -1) {
        this.notifications.splice(index, 1);
      }
    },

    // Delete all notifications
    deleteAllNotifications() {
      this.notifications = [];
    },
  },
});

UI Components for Notifications

Now let's create the UI components for displaying notifications:

Notification Dropdown Component

<!-- NotificationDropDown.vue -->
<script setup>
import { ref, onMounted, computed, inject } from "vue";
import { useRouter } from "vue-router";
import NotificationModal from "./NotificationModal.vue";
import useNotificationService from "@/services/userNotificationService/notificationService";
import { useUserStore } from "@/stores/userStore"; 
import { useNotificationStore } from "@/stores/notificationStore";

// inject notificationModalRef 
const notificationModalRef = inject('notificationModalRef');

const router = useRouter();
const userStore = useUserStore();
const notificationStore = useNotificationStore();
const notificationService = ref(null);

const emit = defineEmits(['close']);

const tabOptions = ref([
  {
    label: "All",
    value: "all",
  },
  {
    label: "Unread",
    value: "unread",
  },
]);

const currentTab = ref("all");
const selectedNotification = ref(null);
const isModalOpen = ref(false);

onMounted(async () => {
  // Initialize notification service if needed
  if (!notificationService.value) {
    notificationService.value = await useNotificationService(userStore);
  }
});

// Filter notifications based on selected tab
const filteredNotifications = computed(() => {
  if (currentTab.value === "all") {
    return notificationStore.notifications;
  } else {
    return notificationStore.getNotificationsByStatus('unread');
  }
});

// Get counts from store
const unreadCount = computed(() => notificationStore.unreadCount);
const notificationCount = computed(() => notificationStore.notifications.length);

const handleTabChange = (tab) => {
  currentTab.value = tab;
};

const openNotificationDetails = (notification) => {
  // Mark as read
  notificationStore.markAsRead(notification.id);

  selectedNotification.value = notification;
  isModalOpen.value = true;
};

const closeModal = () => {
  isModalOpen.value = false;
  selectedNotification.value = null;
};

const markAllAsRead = () => {
  if (unreadCount.value > 0) {
    notificationStore.markAllAsRead();
  }
};

// Format notification time
const formatNotificationTime = (notification) => {
  if (!notification) return '';
  return notification.time;
};

// Redirect to settings
const redirectToSettings = () => {
  router.push({ name: "Settings", query: { tab: "notifications" } });
  emit('close');
};
</script>

<!-- Template section would go here -->

In the header component, we'll add a notification icon to show unread count and toggle the notification dropdown:

<!-- DashboardHeader.vue (partial) -->
<script setup>
import { ref, onMounted, onBeforeUnmount, computed, provide } from "vue";
import NotificationDropDown from "./NotificationComponents/NotificationDropDown.vue";
import { useUserStore } from "@/stores/userStore";
import { useNotificationStore } from "@/stores/notificationStore";
import useNotificationService from "@/services/userNotificationService/notificationService";

// Notification modal reference
const notificationModalRef = ref(null);

// Provide modal reference to child components
provide("notificationModalRef", notificationModalRef);

const userStore = useUserStore();
const notificationStore = useNotificationStore();

// Notification service and state
const USER_NOTIFICATION_INIT_KEY = 'user_notification_service_initialized';
const notificationService = ref(null);
const openNotificationDropdown = ref(false);
const notificationDropdownRef = ref(null);
const notificationIconRef = ref(null);

// Get unread count from the store
const unreadCount = computed(() => notificationStore.unreadCount);

// Toggle notification dropdown
const toggleNotificationDropdown = () => {
  openNotificationDropdown.value = !openNotificationDropdown.value;
  // Close other dropdowns
  openProfileDropdown.value = false;
};

// Function to close dropdowns when clicking outside
const handleClickOutside = (event) => {
  // Ignore modal close actions
  if (event.target.closest('[data-modal-action]')) {
    return;
  }

  // Check for notification dropdown
  if (
    openNotificationDropdown.value && 
    !event.target.closest('[data-notification-trigger]') && 
    notificationDropdownRef.value && 
    !notificationDropdownRef.value.contains(event.target) &&
    (!notificationModalRef.value || !notificationModalRef.value.contains(event.target))
  ) {
    openNotificationDropdown.value = false;
  }
};

// Clean up notification service before logout
const cleanupNotifications = async () => {
  try {
    console.log("Cleaning up notification subscriptions...");

    // If we have a notification service instance, use it
    if (notificationService.value) {
      await notificationService.value.cleanup();
    } 
    // Otherwise, get a new instance to clean up
    else if (localStorage.getItem(USER_NOTIFICATION_INIT_KEY) === 'true') {
      const service = await useNotificationService(userStore);
      await service.cleanup();
    }

    // Remove initialization flag and clear store
    localStorage.removeItem(USER_NOTIFICATION_INIT_KEY);
    notificationStore.deleteAllNotifications();

    console.log("Notification service cleaned up");
  } catch (error) {
    console.error("Error cleaning up notifications:", error);
  }
};

// Provide cleanup function to child components
provide("cleanupNotifications", cleanupNotifications);

// Logout handler
const logout = async () => {
  // Clean up notification service before logout
  await cleanupNotifications();

  // Perform logout API call
  http()
    .get("auth/logout")
    .then((response) => {
      if (response.status === 200 || response.status === 201) {
        authStore.deleteToken();
        userStore.deleteUser();
        router.replace({ name: "signin" });
      }
    });
};

// Set up event listeners
onMounted(async () => {
  document.addEventListener("click", handleClickOutside);

  // Initialize notification service if needed
  if (!notificationService.value) {
    notificationService.value = await useNotificationService(userStore);

    if (localStorage.getItem(USER_NOTIFICATION_INIT_KEY) !== 'true') {
      await notificationService.value.initializeEcho();
      await notificationService.value.requestNotificationPermission();
    }
  }
});

// Clean up event listeners
onBeforeUnmount(() => {
  document.removeEventListener("click", handleClickOutside);
});
</script>

<template>
  <header>
    <!-- Logo and other header content -->

    <div class="header-controls">
      <!-- Notification icon -->
      <div
        ref="notificationIconRef"
        class="notification-icon"
        @click="toggleNotificationDropdown"
        data-notification-trigger
      >
        <!-- Unread indicator -->
        <div v-if="unreadCount > 0" class="unread-badge">
          <p>{{ unreadCount }}</p>
        </div>
        <img src="@/assets/Icons/notifications.svg" alt="notifications" />
      </div>

      <!-- Other header controls -->
    </div>

    <!-- Notification dropdown container -->
    <div ref="notificationDropdownRef">
      <NotificationDropDown
        v-if="openNotificationDropdown"
        @close="toggleNotificationDropdown"
      />
    </div>
  </header>
</template>

Testing and Debugging

For effective debugging of real-time WebSocket connections, our Echo service includes a global debug object that can be accessed from the browser console:

// Access the debug object in your browser console
window.userEchoDebug.getConnectionState() // Check connection state
window.userEchoDebug.getStoredState() // View stored channel subscriptions
window.userEchoDebug.getInstance() // Access the Echo instance

When testing your notification system, check these common issues:

Authentication Errors: Ensure that your Echo instance has the correct authentication token for private channels
Channel Naming: Verify the channel names match between backend and frontend
Event Names: Make sure event names are consistent in Laravel and Vue
Connection Status: Check connection state if notifications aren't being received
Browser Compatibility: Test browser notifications on different platforms

Best Practices

Based on our implementation, here are some best practices for real-time notification systems:

Singleton Pattern: Use a singleton pattern for your Echo instance to avoid multiple connections
Connection Persistence: Store connection state in localStorage to improve reconnection
Channel Subscription Persistence: Save subscribed channels to restore them after page refresh
Visibility Change Handling: Reconnect when the page becomes visible
Clean Separation of Concerns:
- Echo client handles connection
- Notification service manages business logic
- Store manages state
- UI components handle presentation
Proper Cleanup: Clean up resources and disconnect when users log out
Request Notification Permissions Early: Ask for browser notification permission during initialization
Error Handling: Add robust error handling for all WebSocket operations
Format Notifications Consistently: Use a consistent structure for all notification types
Provide Fallbacks: Use in-app notifications as a fallback when browser notifications are denied

Conclusion

Building a real-time notification system with Vue 3, Laravel Echo, and Pusher provides a seamless user experience for your web application. The architecture presented in this article offers a robust solution that:

Maintains connection state across page refreshes
Automatically reconnects when necessary
Provides persistent channel subscriptions
Offers both in-app and browser notifications
Includes proper cleanup on logout

By following this implementation, you've created a complete notification system that's scalable and maintainable. The modular approach makes it easy to add new notification types or modify existing ones without affecting the core functionality.

Remember to secure your WebSocket connections properly and handle authentication errors gracefully. With these considerations in mind, your notification system will provide a reliable and engaging experience for your users.

What improvements or additional features would you add to this notification system? Let me know in the comments!

Integrating AdMob in React Native Expo: A Comprehensive Developer's Guide

Oghenetega Adiri — Sun, 06 Apr 2025 16:45:33 +0000

Integrating AdMob in React Native Expo: A Comprehensive Developer's Guide

Are you looking to monetize your React Native Expo app? Google's AdMob is one of the most popular advertising platforms, and in this guide, I'll walk you through integrating different types of ads into your app.

Prerequisites

Before we start, make sure you have:

An existing React Native Expo project
An AdMob account
A Google Play Developer account (for Android)
Patience and attention to detail 😄

Step 1: Install Required Packages

You have two main options for implementing AdMob in your Expo project:

Option 1: Expo Ads AdMob

expo install expo-ads-admob
npm install @react-native-async-storage/async-storage

Option 2: React Native Google Mobile Ads

npm install react-native-google-mobile-ads
# If using Expo, also run:
expo install @react-native-async-storage/async-storage

Step 2: Set Up Google AdMob Account and Obtain Ad Unit IDs

Creating an AdMob Account

Go to Google AdMob
Sign in with your Google account
Click "Get Started" or "Create Account"

Adding a New App

Click "Apps" in the left sidebar
Click the "Add app" button
Choose your platform (iOS or Android)
Select "I have an app" if your app is already published
- If not published, select "I'm going to publish an app"
Enter your app's name
Select the platform (iOS/Android)

Creating Ad Units

After adding your app, click on "Ad units" in the left sidebar
Click "Add ad unit" button
Choose the ad format:
- Banner Ad: Recommended sizes: 320x50, 300x250, 468x60
- Interstitial Ad: full-screen ads
- Rewarded Ad: optional, for in-app rewards
Name your ad unit descriptively (e.g., "Home Screen Banner", "Game Over Interstitial")
Configure ad unit settings
Click "Create"

Obtaining App and Ad Unit IDs

After creating an ad unit, you'll see two important IDs:

App ID: Starts with ca-app-pub- (used in app.json)
Ad Unit ID: Also starts with ca-app-pub- (used in your code)

Important Notes

Use different ad units for different platforms (iOS/Android)
In development, use test ad units
Replace test IDs with production IDs before publishing
Ensure your app complies with AdMob policies

Example ID Formats

App ID: ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy
Ad Unit ID: ca-app-pub-xxxxxxxxxxxxxxxx/zzzzzzzzzz

Configuring Test Devices

Go to "Settings" > "Test devices"
Add device IDs for testing to avoid account suspension
- On Android, you can get the device ID from logcat when running your app
- On iOS, use Xcode or device logs to find the device identifier

Expo Ads vs React Native Google Mobile Ads: Package Comparison

Expo Ads AdMob (expo-ads-admob)

Pros:

Direct integration with Expo
Easier setup for Expo-managed projects
Minimal configuration required
Lighter weight
Seamless with Expo workflows

Cons:

Limited to Expo-managed projects
Fewer advanced configuration options
Less frequent updates
Limited customization

React Native Google Mobile Ads (react-native-google-mobile-ads)

Pros:

More comprehensive AdMob features
Regularly updated by Google
Advanced configuration options
Works with bare React Native projects
More robust error handling
Better support for latest AdMob features
Supports mediation and advanced ad targeting

Cons:

More complex setup
Requires additional native module configuration
Slightly steeper learning curve
More manual configuration needed

Recommendation

For Expo-managed projects: Use expo-ads-admob
For bare React Native or more advanced projects: Use react-native-google-mobile-ads

Best Practice: If you anticipate ejecting from Expo or need advanced ad features, start with react-native-google-mobile-ads

Configuration Guides

Option 1: Expo Ads AdMob Configuration

Step 3: Configure App.json for AdMob

Update your app.json to include AdMob configuration:

{
  "expo": {
    "plugins": [
      [
        "expo-ads-admob",
        {
          "androidAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy",
          "iosAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"
        }
      ]
    ]
  }
}

Step 4: Create AdMob Component

import React, { useState, useEffect } from 'react';
import { View, Platform } from 'react-native';
import {
  AdMobBanner,
  AdMobInterstitial,
  AdMobRewarded,
  setTestDeviceIDAsync
} from 'expo-ads-admob';

// Define your ad unit IDs
const BANNER_AD_UNIT_ID = Platform.select({
  ios: 'ca-app-pub-xxx/yyy',
  android: 'ca-app-pub-xxx/yyy'
});

const INTERSTITIAL_AD_UNIT_ID = Platform.select({
  ios: 'ca-app-pub-xxx/yyy',
  android: 'ca-app-pub-xxx/yyy'
});

const REWARDED_AD_UNIT_ID = Platform.select({
  ios: 'ca-app-pub-xxx/yyy',
  android: 'ca-app-pub-xxx/yyy'
});

const AdMobManager = ({ style }) => {
  const [isTestMode, setIsTestMode] = useState(true);

  useEffect(() => {
    // Set up test devices during development
    const setupTestDevices = async () => {
      if (isTestMode) {
        await setTestDeviceIDAsync('EMULATOR');
      }
    };

    setupTestDevices();
  }, [isTestMode]);

  // Banner Ad Component
  const BannerAdComponent = () => (
    <AdMobBanner
      bannerSize="smartBannerPortrait"
      adUnitID={BANNER_AD_UNIT_ID}
      servePersonalizedAds={true}
      onAdFailedToLoad={(error) => console.error('Banner Ad Error:', error)}
    />
  );

  // Interstitial Ad Loading and Showing
  const loadInterstitial = async () => {
    try {
      await AdMobInterstitial.setAdUnitID(INTERSTITIAL_AD_UNIT_ID);
      await AdMobInterstitial.requestAdAsync();
      await AdMobInterstitial.showAdAsync();
    } catch (error) {
      console.error('Interstitial Ad Error:', error);
    }
  };

  // Rewarded Ad Loading and Showing
  const loadRewardedAd = async () => {
    try {
      await AdMobRewarded.setAdUnitID(REWARDED_AD_UNIT_ID);
      await AdMobRewarded.requestAdAsync();
      await AdMobRewarded.showAdAsync();
    } catch (error) {
      console.error('Rewarded Ad Error:', error);
    }
  };

  return (
    <View style={[{ alignItems: 'center' }, style]}>
      <BannerAdComponent />
    </View>
  );
};

export default AdMobManager;

Option 2: React Native Google Mobile Ads Configuration

Additional Configuration Steps

iOS (Info.plist)

Add to your ios/YourProject/Info.plist:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

Android (AndroidManifest.xml)

Add to your android/app/src/main/AndroidManifest.xml:

<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>

AdMob Manager Component

import React, { useEffect } from 'react';
import { View, Platform } from 'react-native';
import { 
  MobileAds, 
  BannerAd, 
  BannerAdSize, 
  InterstitialAd, 
  AdEventType,
  TestIds,
  RewardedAd,
  RewardedAdEventType
} from 'react-native-google-mobile-ads';

// Configure Ad Units
const BANNER_AD_UNIT_ID = __DEV__ 
  ? TestIds.BANNER 
  : Platform.select({
      ios: 'ca-app-pub-xxx/yyy',
      android: 'ca-app-pub-xxx/yyy'
    });

const INTERSTITIAL_AD_UNIT_ID = __DEV__ 
  ? TestIds.INTERSTITIAL 
  : Platform.select({
      ios: 'ca-app-pub-xxx/yyy',
      android: 'ca-app-pub-xxx/yyy'
    });

const REWARDED_AD_UNIT_ID = __DEV__ 
  ? TestIds.REWARDED 
  : Platform.select({
      ios: 'ca-app-pub-xxx/yyy',
      android: 'ca-app-pub-xxx/yyy'
    });

const AdMobManager = ({ style }) => {
  useEffect(() => {
    // Initialize MobileAds
    MobileAds()
      .initialize()
      .then(adapterStatuses => {
        // Initialization complete
        console.log('AdMob Initialization complete', adapterStatuses);
      });
  }, []);

  // Banner Ad Component
  const BannerAdComponent = () => (
    <BannerAd
      unitId={BANNER_AD_UNIT_ID}
      size={BannerAdSize.FULL_BANNER}
      requestOptions={{
        requestNonPersonalizedAdsOnly: true,
      }}
      onAdLoaded={() => {
        console.log('Banner ad loaded');
      }}
      onAdFailedToLoad={(error) => {
        console.error('Banner ad failed to load', error);
      }}
    />
  );

  // Interstitial Ad Management
  const loadInterstitial = () => {
    const interstitial = InterstitialAd.createForAdRequest(INTERSTITIAL_AD_UNIT_ID, {
      requestNonPersonalizedAdsOnly: true,
    });

    interstitial.addAdEventListener(AdEventType.LOADED, () => {
      interstitial.show();
    });

    interstitial.addAdEventListener(AdEventType.CLOSED, () => {
      // Ad closed, load a new one
      interstitial.load();
    });

    // Begin loading
    interstitial.load();
  };

  // Rewarded Ad Management
  const loadRewardedAd = () => {
    const rewarded = RewardedAd.createForAdRequest(REWARDED_AD_UNIT_ID, {
      requestNonPersonalizedAdsOnly: true,
    });

    rewarded.addAdEventListener(RewardedAdEventType.LOADED, () => {
      rewarded.show();
    });

    rewarded.addAdEventListener(RewardedAdEventType.EARNED_REWARD, reward => {
      console.log('User earned reward of ', reward);
      // Handle user reward
    });

    // Begin loading
    rewarded.load();
  };

  return (
    <View style={[{ alignItems: 'center' }, style]}>
      <BannerAdComponent />
    </View>
  );
};

export default AdMobManager;

Implementing Ads in Your App

Banner Ads

Simply import and use the AdMobManager component:

import React from 'react';
import { View } from 'react-native';
import AdMobManager from './AdMobManager';

const HomeScreen = () => {
  return (
    <View>
      {/* Your screen content */}
      <AdMobManager style={{ marginTop: 10 }} />
    </View>
  );
};

Interstitial Ads

Trigger at strategic points in your app:

const GameOverScreen = () => {
  const handleGameOver = async () => {
    // Show interstitial ad after game ends
    await loadInterstitial();
  };

  return (
    <View>
      {/* Game over content */}
    </View>
  );
};

Rewarded Ads

Implement in scenarios like extra lives or in-app rewards:

const RewardScreen = () => {
  const handleGetReward = async () => {
    try {
      await loadRewardedAd();
      // Handle reward logic after ad completion
    } catch (error) {
      console.error('Reward Ad Error:', error);
    }
  };

  return (
    <View>
      {/* Reward screen content */}
    </View>
  );
};

Performance Optimization

Load ads before displaying
Handle ad loading errors gracefully
Don't overload your app with too many ads
Respect user experience

Recommended Additional Packages

@react-native-async-storage/async-storage: For storing ad preferences
react-native-device-info: For more precise device targeting

Consent and Privacy

Implement user consent mechanisms:

import { MobileAds } from 'react-native-google-mobile-ads';

// Request consent if required (GDPR compliance)
MobileAds()
  .requestConsent({
    // Configuration options for consent
    debugGeography: DebugGeography.EEA,
  })
  .then(consentInfo => {
    // Handle consent
  });

Troubleshooting

Verify ad unit IDs are correct
Check network connectivity
Use console logs for debugging
Ensure proper SDK initialization

Conclusion

Integrating AdMob requires careful implementation. Follow Google's guidelines, respect user experience, and continuously test your implementation.

Final Code Structure

your-expo-project/
│
├── components/
│   └── AdMobManager.js
│
├── screens/
│   ├── HomeScreen.js
│   ├── GameOverScreen.js
│   └── RewardScreen.js
│
└── app.json

Happy monetizing! 💰📱

I hope this guide helps you successfully integrate AdMob into your React Native Expo app! Feel free to leave questions in the comments below.

DEV Community: Oghenetega Adiri

Building Robust Offline Functionality in React Native: A Complete Guide

Introduction

Table of Contents

Architecture Overview

Storage Strategy

Handling Storage Size Limits

Structured Storage with Metadata

Network State Management

Offline Queue Implementation

Queue Structure

Adding Items to Queue

Intelligent Retry Logic

Data Synchronization

Unified Verification Approach

Offline Data Verification

Bidirectional Sync

Context-Based State Management

App-Wide Context

Feature-Specific Context

Handling Edge Cases

Stale Data Detection

Conflict Resolution

Cache Invalidation

Best Practices

1. Always Use Refs for Cleanup

2. Implement Progressive Loading

3. Provide Clear User Feedback

4. Implement Exponential Backoff

5. Log Everything

6. Test Offline Scenarios

7. Monitor Performance

Conclusion

Resources

Converting Your Website to a PWA: A Comprehensive Guide

What are Progressive Web Apps?

Converting Traditional HTML/CSS/JavaScript Websites to PWAs

Step 1: Create a Web App Manifest

Step 2: Add iOS Support

Step 3: Implement a Service Worker

Step 4: Implement "Add to Home Screen" Experience

Step 5: Test Your Traditional PWA

Converting React and Vue Applications to PWAs

React Implementation

Vue Implementation

Best Practices I've Learned Along the Way

Conclusion

IndexedDB vs localStorage: When to Use Which?

The TL;DR Version

localStorage: The Simple One 📦

Quick Facts:

How to Use localStorage

LocalStorage Pro Tips 💡

IndexedDB: The Powerhouse 💪

Quick Facts:

How to Use IndexedDB

Modern IndexedDB with Promises

The Ultimate Comparison 🥊

When to Use What? 🤔

Use localStorage when:

Use IndexedDB when:

Real-World Examples

localStorage: User Preferences

IndexedDB: Offline-First Todo App

Pro Tips for Both

Conclusion 🎉

Real-Time Private Channel Notifications in Vue 3 with Laravel Echo and Pusher

Table of Contents

Prerequisites

Understanding the Architecture

Setting Up Laravel Echo

Creating a Notification Service

Building the Notification Store

UI Components for Notifications

Notification Dropdown Component

Testing and Debugging

Best Practices

Conclusion

Integrating AdMob in React Native Expo: A Comprehensive Developer's Guide

Integrating AdMob in React Native Expo: A Comprehensive Developer's Guide