Skip to main content

Uppy 4.0 is here: TypeScript rewrite, Google Photos, React hooks, and much more.

Golden Retriever

The @uppy/golden-retriever plugin saves selected files in your browser cache, so that if the browser crashes, or the user accidentally closes the tab, Uppy can restore everything and continue uploading as if nothing happened. You can read more about it on our blog.

The Golden Retriever uses three methods of browser data storage:

  • LocalStorage to store file metadata and Uppy state only.
  • IndexedDB for small files, usually under 5MiB.
  • Service Worker (optional) for all files because, unlike IndexedDB, Service Worker can keep references to large files. Service Worker storage is quite temporary though, and doesn’t persist across browser crashes or restarts. It works well, however, for accidental refreshes or closed tabs.

Upon restore, the plugin first restores state from LocalStorage and then checks both file storages — IndexedDB and ServiceWorker — merging the results.

If restore is unsuccessful for certain files, they will be marked as “ghosts” in the Dashboard UI, and a message + button offering to re-select those files will be displayed.

Checkout the storage quotas on MDN to see how much data can be stored depending on the device and browser.

When should I use this?​

When you want extra insurance for the user-selected files. If you feel like users might spend some time picking files, tweaking descriptions etc, and will not appreciate having to do it over again if something crashes. Another use case might be when you think user might want to pick a few files, navigate away to do something else in your app or otherwise, and then come back to the same selection.

Install​

npm install @uppy/golden-retriever

Use​

import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import GoldenRetriever from '@uppy/golden-retriever';

new Uppy()
  .use(Dashboard, {inline:true, target: '#dashboard')
  .use(GoldenRetriever);

By default, Golden Retriever will only use the IndexedDB storage, which is good enough for files up to 5 MiB. Service Worker is optional and requires setup.

Enabling Service Worker​

With the Service Worker storage, Golden Retriever will be able to temporary store references to large files.

  1. Bundle your own service worker sw.js file with Uppy GoldenRetriever’s service worker.

    tip

    For Webpack, check out serviceworker-webpack-plugin.

    sw.js
    import '@uppy/golden-retriever/lib/ServiceWorker';

  2. Register it in your app’s entry point:

    // you app.js entry point
    uppy.use(GoldenRetriever, { serviceWorker: true });

    if ('serviceWorker' in navigator) {
    	navigator.serviceWorker
    		.register('/sw.js') // path to your bundled service worker with GoldenRetriever service worker
    		.then((registration) => {
    			console.log(
    				'ServiceWorker registration successful with scope: ',
    				registration.scope,
    			);
    		})
    		.catch((error) => {
    			console.log(`Registration failed with ${error}`);
    		});
    }

Voilà, that’s it. Happy retrieving!

API​

Options​

id​

A unique identifier for this plugin (string, default: 'GoldenRetriever').

expires​

How long to store metadata and files for. Used for LocalStorage and IndexedDB (number, default: 24 * 60 * 60 * 1000 // 24 hours).

serviceWorker​

Whether to enable Service Worker storage (boolean, default: false).