uppy/docs/golden-retriever.mdx

---
sidebar_position: 11
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import UppyCdnExample from '/src/components/UppyCdnExample';

# 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](https://uppy.io/blog/2017/07/golden-retriever/).

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](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#other_web_technologies)
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

<Tabs>
  <TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/golden-retriever
```

  </TabItem>

  <TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/golden-retriever
```

  </TabItem>

  <TabItem value="cdn" label="CDN">
    <UppyCdnExample>
      {`
        import { Uppy, GoldenRetriever } from "{{UPPY_JS_URL}}"
        new Uppy().use(GoldenRetriever)
      `}
    </UppyCdnExample>
  </TabItem>
</Tabs>

## Use

```js {7} showLineNumbers
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](https://github.com/oliviertassinari/serviceworker-webpack-plugin).

   :::

   ```js title="sw.js"
   import('@uppy/golden-retriever/lib/ServiceWorker');
   ```

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

   ```js
   // 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`).