What Nobody Tells You About Browser Storage: The Storage Buckets API Is Your Only Shield Against Data Eviction

I used to treat IndexedDB like a digital vault—a safe, permanent home for user data where I could store megabytes of offline content and sleep soundly at night. Then I started seeing the bug reports. Users would return to an app after two weeks of inactivity only to find their entire local database wiped clean. No error messages, no warnings, just a hollow count() === 0.

I realized then that "persistent" storage in the browser is often a polite suggestion, not a guarantee. Browsers are ruthless landlords; if the device starts running low on disk space, your app's data is the first thing getting evicted to make room for system updates or cat videos.

Until now, we had one blunt tool: navigator.storage.persist(). It was an all-or-nothing gamble that browsers often ignored. The Storage Buckets API changes the game by letting us organize data into prioritized groups.

The "Best Effort" Lie

By default, everything you store—LocalStorage, Cache API, IndexedDB—is classified as "Best Effort."

When the browser's eviction algorithm kicks in (and it will), it doesn't look at how important that specific draft_post table is to your user. It looks at the origin as a whole. If your origin is taking up too much space and hasn't been visited recently, *poof*. Everything is deleted.

Storage Buckets allow you to create "buckets" of data with different expiration policies and persistence guarantees. You can put non-essential assets (like UI icons) in one bucket that can be wiped safely, while keeping critical user-generated content in a "persistent" bucket that the browser will fight to keep alive.

Step 1: Checking for Support

This API is still landing in browsers (Chromium-based browsers are leading the charge), so we need to be defensive.

if ('storageBuckets' in navigator) {
  console.log("We have buckets! Time to organize.");
} else {
  console.log("Back to the old 'pray it stays' method.");
}

Step 2: Creating a "High Priority" Bucket

Let's say you're building a markdown editor. You have "Drafts" (critical) and "App Themes" (cached assets). You don't want a theme update to be the reason a user loses their 2,000-word essay.

Here is how you create a bucket that asks the browser for a pinky-promise not to delete it:

async function setupCriticalBucket() {
  try {
    const draftsBucket = await navigator.storageBuckets.open('user-drafts', {
      durability: 'strict', // Ensures data is written to disk before resolving
      persistency: 'persistent', // Tells the browser: "Don't evict this unless the user says so"
    });
    
    console.log('Bucket created successfully!');
    return draftsBucket;
  } catch (error) {
    console.error('Bucket creation failed:', error);
  }
}

The persistency: 'persistent' flag is the secret sauce. While it's not a 100% guarantee (nothing is if the user wipes their settings), it moves your data into a "protected" tier that skips the standard eviction logic.

Step 3: Using IndexedDB Inside a Bucket

This is where people get tripped up. You don't just use indexedDB.open() like usual. You have to open the database *through* the bucket instance. This "scopes" the database to that specific storage policy.

async function saveDraft(draftContent) {
  const bucket = await navigator.storageBuckets.open('user-drafts');
  
  // Notice we call .indexedDB on the bucket, not the global window
  const dbRequest = bucket.indexedDB.open('DraftsDB', 1);

  dbRequest.onupgradeneeded = (event) => {
    const db = event.target.result;
    db.createObjectStore('drafts', { keyPath: 'id' });
  };

  dbRequest.onsuccess = (event) => {
    const db = event.target.result;
    const tx = db.transaction('drafts', 'readwrite');
    tx.objectStore('drafts').put({ id: 'latest', content: draftContent });
    console.log("Draft saved safely in a persistent bucket.");
  };
}

Why This Actually Matters

Imagine you're building a Progressive Web App (PWA). Currently, if you store 500MB of map tiles in the Cache API and 10KB of user settings in IndexedDB, the browser sees 500.01MB of data. If it needs space, it wipes the whole origin.

With Storage Buckets, you can do this:
1. Bucket A (Cache API): Set to durability: 'relaxed'. If the browser needs 400MB, it can toss this.
2. Bucket B (IndexedDB): Set to persistency: 'persistent'. The browser leaves this alone.

You’ve essentially compartmentalized your risk.

The "Gotchas" You Need to Know

No API is perfect, and this one has some quirks:

* Quota Limits: Even with buckets, you're still bound by the overall origin quota. You can't just claim 50GB of "persistent" space if the disk only has 10GB free.
* User Permission: Browsers may prompt the user if you request a persistent bucket, or they may use internal heuristics (like "Is this app installed as a PWA?") to grant it silently.
* Introspection: You can check what buckets exist and delete them when they’re no longer needed using navigator.storageBuckets.keys() and delete().

// Housekeeping: Delete old temporary buckets
const bucketNames = await navigator.storageBuckets.keys();
for (const name of bucketNames) {
  if (name.startsWith('temp-')) {
    await navigator.storageBuckets.delete(name);
  }
}

Wrapping Up

Storage in the browser has always felt a bit like building a house on shifting sand. You hope it's still there when you get back, but you're never quite sure. The Storage Buckets API finally gives us a way to pour a concrete foundation for the data that actually matters.

If you're building anything more complex than a "Hello World"—especially if it involves offline work—stop relying on global IndexedDB. Start bucketizing your data. Your users (and their data) will thank you.