Auto-saving extension data to the Downloads folder in Manifest V3: 8 things that broke

elite kid — Fri, 25 Sep 2026 13:00:13 +0000

Disclosure: this post was generated by an AI agent (Claude) with no human editing, working from the extension's source code and our own test notes. The code excerpts are copied from the repository, and the measurements come from our runs on Chrome for Testing 153 and Firefox 155 in September 2026. Every claim was checked against the code and those notes before publishing.

When a user removes a Chrome extension, its local storage goes with it. The Chrome docs say it plainly for storage.local: "Data is stored locally and cleared when the extension is removed." For a tab manager, that means every saved list disappears with one click on Remove, an accidental uninstall, or a deleted browser profile.

We wanted a copy that survives that: a plain JSON file in the user's Downloads folder, rewritten automatically shortly after every change, with no server, no account and no file picker. The obvious API is downloads.download(). Making it reliable from a Manifest V3 background took more edge cases than we expected. The code below is from TabBunker, an open-source (MIT) tab manager for Chrome, Edge and Firefox. The source link is at the end.

The shape of it

One file that is always current: Downloads/TabBunker/tabbunker-latest.json, written with conflictAction: 'overwrite'.
Dated snapshots next to it (tabbunker-20260925-0912.json), written with conflictAction: 'uniquify': at most one per hour, only when something changed, newest 30 kept.
A write is scheduled 30 seconds (by default) after the first unsaved change, with chrome.alarms, because the service worker may not be alive 30 seconds later.

1. No `URL.createObjectURL` in a Chrome MV3 service worker, and Firefox rejects `data:` URLs

The usual way to hand a string to downloads.download() is a Blob URL. In a Chrome MV3 service worker, URL.createObjectURL does not exist. A data: URL works there. Firefox runs the MV3 background as an event page, which does have createObjectURL, and in our tests it refused a data: URL download with "Access denied". So we feature-detect:

function makeUrl(body) {
  const canBlob = typeof URL.createObjectURL === 'function';
  if (canBlob) {
    return URL.createObjectURL(new Blob([body], { type: 'application/json' }));
  }
  return 'data:application/json;charset=utf-8,' + encodeURIComponent(body);
}

We worried about size limits on the data: path, so we measured it: JSON files of 1, 2, 4, 8, 16, 32 and 64 MB all completed in Chrome for Testing 153 (64 MB took about 1.3 seconds). Real vaults are far smaller, so we dropped the "file too large" error case from our design. On the Blob path, revoke the URL once the download settles.

2. `overwrite` really overwrites, but the download history keeps growing

We checked that conflictAction: 'overwrite' behaves the same in both browsers: two downloads to the same relative path left one file on disk with the second content, and both items reported complete. Every write still adds an entry to the browser's download history, though. Rewriting a file every few minutes would bury the user's real downloads, so after a new latest completes we erase the history entry of the previous one:

if (prevLatest && prevLatest !== id) {
  try {
    await downloads.erase({ id: prevLatest });
  } catch {
    /* ignore */
  }
}

erase removes only the history entry. The file on disk is the one the new download just wrote.

3. Deleting old snapshots: `removeFile` first, then `erase`

downloads.removeFile(id) deletes the file (only if it exists and the item is complete), and downloads.erase({ id }) deletes the history entry. The order matters: after erase there is no item left, so a later removeFile fails. If the user already deleted the file by hand, the item reports exists: false and we only erase:

if (!item || item.exists === false) {
  await downloads.erase({ id: oldest.downloadId });
} else {
  await downloads.removeFile(oldest.downloadId);
  await downloads.erase({ id: oldest.downloadId });
}

(Simplified: the real loop wraps both branches in try/catch.) If deleting the same file fails three times, we stop writing new snapshots and show it, instead of looping.

4. You can't find your own file by the name you gave it

Our first idea was to look files up with downloads.search(). In Chrome 153, filenameRegex matches the absolute path: TBProbe/size-1mb\.json$ found the file, ^TBProbe/... found nothing, and { filename: 'TBProbe/size-1mb.json' }, the exact relative path we had passed in, returned zero results. The reliable handle is the id that downloads.download() resolves with, so we store it for the in-flight write, for the current latest, and for every dated snapshot.

5. "Ask where to save each file" applies to extensions too

In Chrome, saveAs: false does not override the browser setting. With "Ask where to save each file before downloading" turned on, our extension-initiated download ended as interrupted with USER_CANCELED after 277 ms (in a headless run the dialog closed at once; a real user sees a save dialog). A retry loop would pop that dialog every 30 seconds. So USER_CANCELED is not retried. It pauses automatic backup until the user acts:

if (code === 'canceled') {
  await saveBackupState({
    ...state,
    paused: 'canceled',
    inflight: null,
    lastError: { code: 'canceled', detail: '', at: Date.now() },
  });
  return;
}

The other interrupt reasons are classified too. USER_SHUTDOWN and CRASH only clear the in-flight marker, so the next start writes again. Everything else (disk full, access denied, unknown) is recorded as a visible error and retried after 5 minutes, then every 30 minutes.

Firefox documents that saveAs: false suppresses the dialog there. We have not measured that part.

6. The service worker can stop in the middle of a download

A download outlives the worker that started it. Three things made that safe for us:

Store the download id right after downloads.download() resolves, before waiting on anything.
Register downloads.onChanged synchronously at the top level of the background script. Chrome dispatches the event that woke a stopped worker to the listeners registered during that first run of the script; one added later inside an async function can miss it.
Set a 2-minute watchdog alarm. When it fires, look the stored id up with downloads.search({ id }). If the item finished or was interrupted, settle it. If it is still running after two minutes, record it as stalled and schedule a retry.

browserApi.downloads.onChanged.addListener((delta) => {
  if (!delta.state) return;
  enqueue('downloadChanged', async () => {
    await ready;
    const items = await downloads.search({ id: delta.id });
    if (items[0]) await settleDownload(items[0]);
    await restoreDownloadUiIfIdle();
  }).catch(console.error);
});

enqueue runs edits, alarm handlers and download events one at a time, so two handlers never read-modify-write the backup state at once.

7. A "dirty" flag loses edits; a revision counter doesn't

One of the design drafts we compared kept a boolean: set dirty = true on every edit, set it back to false when a backup completes. Walk through this: the backup of revision R starts, the user edits (now R+1, dirty = true), then the R download completes and sets dirty = false. The file on disk is R, the extension thinks it is up to date, and the R+1 edit waits for the next unrelated change.

A monotonic revision fixes it. Every edit bumps meta.revision, each write remembers the revision it captured, and completion keeps the maximum:

function isDirty(meta, state) {
  return (meta?.revision ?? 0) > (state?.lastFileOkRevision ?? 0);
}

// when the write that captured revision R completes:
lastFileOkRevision: Math.max(state.lastFileOkRevision || 0, R),

An edit made during the download leaves meta.revision > R, so the next backup is still due.

8. Alarms: a 30-second floor, and don't re-create them on every wake-up

Chrome MV3 alarms can't fire sooner than 30 seconds. In our measurements delayInMinutes: 0.5 fired after 30.1 s and 1 after 60.0 s, so minute-level delays are precise.

The subtler bug: alarms.create() with an existing name replaces that alarm. Our design draft called it at the top level for a daily trash cleanup (periodInMinutes: 1440). The service worker starts many times a day, so every start would push the next run another 24 hours out and the cleanup would practically never run. A review pass caught it before release, and the code checks first:

async function ensureTrashAlarm() {
  const existing = await alarms.get(ALARM_TRASH);
  if (!existing) {
    await alarms.create(ALARM_TRASH, { periodInMinutes: 1440 });
  }
}

Also: the download bubble (Chrome and Edge only)

A backup that pops the download bubble every few minutes is noise. Chrome and Edge have downloads.setUiOptions({ enabled: false }), which needs the downloads.ui permission. We turn the UI off only while an automatic backup is in flight and turn it back on when nothing is pending, including after a failure. Firefox has no equivalent API, so its downloads panel may open briefly. We tell Firefox users that once instead of hiding it.

A testing trap

We drive Chrome for Testing with Puppeteer and used the CDP command Browser.setDownloadBehavior to keep test files out of the real Downloads folder. It does not apply to downloads an extension starts through the downloads API: our probe files landed in the real ~/Downloads. A review of the test plan pointed out what that meant for the full scenario: it would overwrite the developer's own Downloads/TabBunker/tabbunker-latest.json. The test scripts now switch the backup subfolder to a dedicated name (TabBunkerSmoke-<pid>) and clean up only their own download ids with removeFile and then erase.

Does restoring actually work?

The file only matters if it restores. We ran the whole loop in Chrome on 2026-09-23: saved 10 tabs in a fresh profile, waited for the file, installed the extension in a second, empty profile, and imported the file. Titles, URLs and order matched. Import first shows how many groups and links the file has and asks whether to merge or replace. We have not run the same end-to-end check on Edge or Firefox yet.

Limits

The file is plain JSON in Downloads. Anyone who can read that folder can read the saved URLs.
If the file is deleted or the disk fails, there is nothing else to restore from, and nothing syncs between devices.
On Firefox the downloads panel can flash during a backup.

A question for you

If you have shipped file-based backups from an extension, how do you handle users who have "Ask where to save each file" turned on? Pausing was the least annoying option we found, but it means those users get no automatic backup until they change the setting.

Source: https://github.com/elitekid/tabbunker (MIT). The backup code is in src/background.js.

DEV Community: elite kid