Skip to main content

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 these methods of browser data storage:

  • IndexedDB to store file metadata and Uppy state, and for small files, up to 10MiB per file by default.
  • LocalStorage for file metadata and Uppy state when window.indexedDB is not available. The plugin picks a store once, when it is installed; it does not move to LocalStorage later on.
  • 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 whichever of IndexedDB or LocalStorage it stored it in, 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 stores metadata, state, and local files up to 10 MiB in IndexedDB. If IndexedDB is unavailable, metadata and state fall back to LocalStorage, but local files require the optional Service Worker storage to be restorable.

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.

    For vite, you can add this to your vite.config.ts:

      build: {
       rollupOptions: {
         input: {
           main: './index.html',
           sw: './sw.js',
         },
         output: {
           entryFileNames: (chunk) => {
             if (chunk.name === 'sw') return 'sw.js' // force predictable filename
             return 'assets/[name].[hash].js'
           },
         },
       },
     },
    sw.js
    import '@uppy/golden-retriever/lib/ServiceWorker.js';

  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', { type: 'module' }) // path to your bundled service worker which imports 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 IndexedDB and, when window.indexedDB is not available, LocalStorage (number, default: 24 * 60 * 60 * 1000 // 24 hours).

serviceWorker​

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