Chrome Extension Local Storage Viewer: Complete Guide for Developers

Chrome extension development frequently involves working with storage APIs to persist user preferences, cached data, or application state. Understanding how to view and debug these storage mechanisms is essential for building robust extensions. This guide covers the methods and tools available for inspecting localStorage and sessionStorage within Chrome extensions.

Understanding Chrome Extension Storage Types

Chrome extensions can use multiple storage mechanisms, each with different characteristics and use cases.

localStorage provides persistent key-value storage that survives browser restarts. Data stored here remains until explicitly removed by the extension or by the user clearing browser data.

sessionStorage stores data for only one session—the data is deleted when the browser tab closes. This works well for temporary state that should not persist across sessions.

chrome.storage is the recommended storage API for Chrome extensions. It offers synchronous access, larger storage quotas, and the ability to sync data across devices when using the sync storage area.

Viewing Storage in Chrome DevTools

The most straightforward method for inspecting extension storage involves Chrome DevTools.

Open DevTools in your Chrome browser by pressing F12 or right-clicking anywhere on a page and selecting “Inspect.” Navigate to the “Application” tab—this panel contains all storage inspection tools.

In the left sidebar under “Storage,” expand “Local Storage” and “Session Storage” to see available origins. Click on your extension’s ID to view all stored key-value pairs. You can edit values directly by double-clicking on any entry, add new entries with the “+” button, or delete entries using the context menu.

For chrome.storage, expand “Extension Storage” in the same panel. This shows data from both local and sync storage areas. The interface supports the same editing capabilities as standard localStorage inspection.

Building a Custom Local Storage Viewer Extension

Creating your own storage viewer provides more control and customization than relying solely on DevTools. Here is a practical implementation:

Manifest Configuration

{
  "manifest_version": 3,
  "name": "Storage Viewer",
  "version": "1.0",
  "permissions": ["storage", "activeTab"],
  "action": {
    "default_popup": "popup.html"
  }
}

<!DOCTYPE html>
<html>
<head>
  <style>
    body { width: 400px; padding: 16px; font-family: system-ui; }
    .storage-section { margin-bottom: 16px; }
    h3 { margin-bottom: 8px; }
    pre { background: #f4f4f4; padding: 8px; overflow-x: auto; }
    button { margin: 4px 0; padding: 6px 12px; }
  </style>
</head>
<body>
  <div class="storage-section">
    <h3>Local Storage</h3>
    <pre id="local-storage"></pre>
    <button id="clear-local">Clear Local Storage</button>
  </div>
  <div class="storage-section">
    <h3>Chrome Storage (Local)</h3>
    <pre id="chrome-storage"></pre>
    <button id="clear-chrome">Clear Chrome Storage</button>
  </div>
  <script src="popup.js"></script>
</body>
</html>

// popup.js

// Read and display localStorage
function displayLocalStorage() {
  const output = document.getElementById('local-storage');
  const data = {};
  
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i);
    data[key] = localStorage.getItem(key);
  }
  
  output.textContent = JSON.stringify(data, null, 2);
}

// Read and display chrome.storage.local
function displayChromeStorage() {
  chrome.storage.local.get(null, (items) => {
    const output = document.getElementById('chrome-storage');
    output.textContent = JSON.stringify(items, null, 2);
  });
}

// Clear localStorage
document.getElementById('clear-local').addEventListener('click', () => {
  localStorage.clear();
  displayLocalStorage();
});

// Clear chrome.storage.local
document.getElementById('clear-chrome').addEventListener('click', () => {
  chrome.storage.local.clear(() => {
    displayChromeStorage();
  });
});

// Initialize displays
displayLocalStorage();
displayChromeStorage();

This basic implementation provides a functional popup that displays storage contents and allows clearing data. You can extend this with features like search filtering, value editing, or exporting storage to JSON.

Accessing Storage from Background Scripts

Background scripts often need to manage storage on behalf of the extension. Here is how to work with chrome.storage in background contexts:

// background.js

// Store data
chrome.storage.local.set({ userPreferences: { theme: 'dark', notifications: true } });

// Retrieve data
chrome.storage.local.get('userPreferences', (result) => {
  console.log('User preferences:', result.userPreferences);
});

// Listen for storage changes
chrome.storage.onChanged.addListener((changes, areaName) => {
  console.log('Storage changed in:', areaName);
  console.log('Changes:', changes);
});

// Sync across devices
chrome.storage.sync.set({ preference: 'value' }, () => {
  console.log('Stored with sync');
});

The sync storage area automatically syncs data across all instances of Chrome where the user is signed in. This area has a smaller quota than local storage—typically around 100KB.

Debugging Storage Issues

Storage-related bugs can be difficult to diagnose without proper visibility. Several common issues have straightforward solutions.

Storage quota exceeded occurs when you attempt to store more data than allowed. localStorage typically provides around 5MB. chrome.storage.local offers around 5MB as well, while sync storage is more limited. Monitor usage with:

chrome.storage.local.getBytesInUse(null, (bytes) => {
  console.log(`Using ${bytes} bytes`);
});

Data not persisting often results from using sessionStorage when you need persistence, or from the extension’s content script running in an isolated world where localStorage is not shared with the page. Use chrome.storage for data that must persist reliably.

Race conditions can occur when reading storage immediately after writing. The chrome.storage API is asynchronous—always use the callback or Promise returned by get() and set() methods before relying on stored values.

Best Practices for Extension Storage

When designing your extension’s storage strategy, consider these recommendations.

Use chrome.storage instead of localStorage whenever possible. The extension storage API provides better performance, larger quotas, and cross-device synchronization.

Separate storage keys into logical groups to make debugging easier. Instead of storing everything under a single key, use multiple keys:

// Good: organized storage
chrome.storage.local.set({
  'settings-theme': 'dark',
  'settings-notifications': true,
  'cache-user-profile': userProfile,
  'cache-recent-items': items
});

Implement storage cleanup to prevent unbounded growth. Define retention policies and remove stale data:

chrome.storage.local.get(null, (items) => {
  const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
  
  Object.keys(items).forEach(key => {
    if (items[key].timestamp && items[key].timestamp < thirtyDaysAgo) {
      chrome.storage.local.remove(key);
    }
  });
});

Always handle storage errors gracefully. Storage operations can fail due to quota limits or corruption:

chrome.storage.local.set({ key: 'value' }).catch((error) => {
  console.error('Storage error:', error);
  // Implement fallback or user notification
});

Understanding how to view and manage storage is fundamental to Chrome extension development. Whether you rely on DevTools for quick inspection or build custom viewer interfaces, having visibility into your extension’s storage enables faster debugging and more reliable applications.

Built by theluckystrike — More at zovo.one