1"use strict";(globalThis.webpackChunkuppy_io=globalThis.webpackChunkuppy_io||[]).push([[3734],{18409:(e,r,n)=>{n.r(r),n.d(r,{assets:()=>h,contentTitle:()=>c,default:()=>x,frontMatter:()=>a,metadata:()=>i,toc:()=>p});const i=JSON.parse('{"id":"golden-retriever","title":"Golden Retriever","description":"The @uppy/golden-retriever plugin saves selected files in your browser cache,","source":"@site/docs/golden-retriever.mdx","sourceDirName":".","slug":"/golden-retriever","permalink":"/docs/golden-retriever","draft":false,"unlisted":false,"editUrl":"https://github.com/transloadit/uppy.io/blob/main/docs/golden-retriever.mdx","tags":[],"version":"current","sidebarPosition":11,"frontMatter":{"sidebar_position":11},"sidebar":"tutorialSidebar","previous":{"title":"Internationalisation","permalink":"/docs/locales"},"next":{"title":"Compressor","permalink":"/docs/compressor"}}');var s=n(74848),t=n(28453),o=n(11470),l=n(19365),d=n(65171);const a={sidebar_position:11},c="Golden Retriever",h={},p=[{value:"When should I use this?",id:"when-should-i-use-this",level:2},{value:"Install",id:"install",level:2},{value:"Use",id:"use",level:2},{value:"Enabling Service Worker",id:"enabling-service-worker",level:3},{value:"API",id:"api",level:2},{value:"Options",id:"options",level:3},{value:"<code>id</code>",id:"id",level:4},{value:"<code>expires</code>",id:"expires",level:4},{value:"<code>serviceWorker</code>",id:"serviceworker",level:4}];function u(e){const r={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(r.header,{children:(0,s.jsx)(r.h1,{id:"golden-retriever",children:"Golden Retriever"})}),"\n",(0,s.jsxs)(r.p,{children:["The ",(0,s.jsx)(r.code,{children:"@uppy/golden-retriever"})," plugin saves selected files in your browser cache,\nso that if the browser crashes, or the user accidentally closes the tab, Uppy\ncan restore everything and continue uploading as if nothing happened. You can\nread more about it\n",(0,s.jsx)(r.a,{href:"https://uppy.io/blog/2017/07/golden-retriever/",children:"on our blog"}),"."]}),"\n",(0,s.jsx)(r.p,{children:"The Golden Retriever uses these methods of browser data storage:"}),"\n",(0,s.jsxs)(r.ul,{children:["\n",(0,s.jsxs)(r.li,{children:[(0,s.jsx)(r.code,{children:"IndexedDB"})," to store file metadata and Uppy state, and for small files, up to\n10MiB per file by default."]}),"\n",(0,s.jsxs)(r.li,{children:[(0,s.jsx)(r.code,{children:"LocalStorage"})," for file metadata and Uppy state when ",(0,s.jsx)(r.code,{children:"window.indexedDB"})," is not\navailable. The plugin picks a store once, when it is installed; it does not\nmove to ",(0,s.jsx)(r.code,{children:"LocalStorage"})," later on."]}),"\n",(0,s.jsxs)(r.li,{children:[(0,s.jsx)(r.code,{children:"Service Worker"})," (",(0,s.jsx)(r.em,{children:"optional"}),") for ",(0,s.jsx)(r.em,{children:"all"})," files because, unlike ",(0,s.jsx)(r.code,{children:"IndexedDB"}),",\n",(0,s.jsx)(r.code,{children:"Service Worker"})," can keep references to large files. Service Worker storage is\n",(0,s.jsx)(r.em,{children:"quite"})," temporary though, and doesn\u2019t persist across browser crashes or\nrestarts. It works well, however, for accidental refreshes or closed tabs."]}),"\n"]}),"\n",(0,s.jsxs)(r.p,{children:["Upon restore, the plugin first restores state from whichever of ",(0,s.jsx)(r.code,{children:"IndexedDB"})," or\n",(0,s.jsx)(r.code,{children:"LocalStorage"})," it stored it in, and then checks both file storages (",(0,s.jsx)(r.code,{children:"IndexedDB"}),"\nand ",(0,s.jsx)(r.code,{children:"ServiceWorker"}),"), merging the results."]}),"\n",(0,s.jsx)(r.p,{children:"If restore is unsuccessful for certain files, they will be marked as \u201cghosts\u201d in\nthe Dashboard UI, and a message + button offering to re-select those files will\nbe displayed."}),"\n",(0,s.jsxs)(r.p,{children:["Checkout the\n",(0,s.jsx)(r.a,{href:"https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#other_web_technologies",children:"storage quotas"}),"\non MDN to see how much data can be stored depending on the device and browser."]}
1),"\n",(0,s.jsx)(r.h2,{id:"when-should-i-use-this",children:"When should I use this?"}),"\n",(0,s.jsx)(r.p,{children:"When you want extra insurance for the user-selected files. If you feel like\nusers might spend some time picking files, tweaking descriptions etc, and will\nnot appreciate having to do it over again if something crashes. Another use case\nmight be when you think user might want to pick a few files, navigate away to do\nsomething else in your app or otherwise, and then come back to the same\nselection."}),"\n",(0,s.jsx)(r.h2,{id:"install",children:"Install"}),"\n",(0,s.jsxs)(o.A,{children:[(0,s.jsx)(l.A,{value:"npm",label:"NPM",default:!0,children:(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-shell",children:"npm install @uppy/golden-retriever\n"})})}),(0,s.jsx)(l.A,{value:"yarn",label:"Yarn",children:(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-shell",children:"yarn add @uppy/golden-retriever\n"})})}),(0,s.jsx)(l.A,{value:"cdn",label:"CDN",children:(0,s.jsx)(d.A,{children:'\n import { Uppy, GoldenRetriever } from "{{UPPY_JS_URL}}
1"\n new Uppy().use(GoldenRetriever)\n '})})]}),"\n",(0,s.jsx)(r.h2,{id:"use",children:"Use"}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-js",metastring:"{7} showLineNumbers",children:"import Uppy from '@uppy/core';\nimport Dashboard from '@uppy/dashboard';\nimport GoldenRetriever from '@uppy/golden-retriever';\n\nnew Uppy()\n\t.use(Dashboard, { inline: true, target: '#dashboard' })\n\t.use(GoldenRetriever);\n"})}),"\n",(0,s.jsx)(r.p,{children:"By default, Golden Retriever stores metadata, state, and local files up to 10\nMiB in IndexedDB. If IndexedDB is unavailable, metadata and state fall back to\nLocalStorage, but local files require the optional Service Worker storage to be\nrestorable."}),"\n",(0,s.jsx)(r.h3,{id:"enabling-service-worker",children:"Enabling Service Worker"}),"\n",(0,s.jsx)(r.p,{children:"With the Service Worker storage, Golden Retriever will be able to temporary\nstore references to large files."}),"\n",(0,s.jsxs)(r.ol,{children:["\n",(0,s.jsxs)(r.li,{children:["\n",(0,s.jsxs)(r.p,{children:["Bundle your own service worker ",(0,s.jsx)(r.code,{children:"sw.js"})," file with Uppy GoldenRetriever\u2019s\nservice worker."]}),"\n",(0,s.jsxs)(r.admonition,{type:"tip",children:[(0,s.jsxs)(r.p,{children:["For Webpack, check out\n",(0,s.jsx)(r.a,{href:"https://github.com/oliviertassinari/serviceworker-webpack-plugin",children:"serviceworker-webpack-plugin"}),"."]}),(0,s.jsxs)(r.p,{children:["For vite, you can add this to your ",(0,s.jsx)(r.code,{children:"vite.config.ts"}),":"]}),(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-ts",children:" build: {\n rollupOptions: {\n input: {\n main: './index.html',\n sw: './sw.js',\n },\n output: {\n entryFileNames: (chunk) => {\n if (chunk.name === 'sw') return 'sw.js' // force predictable filename\n return 'assets/[name].[hash].js'\n },\n },\n },\n },\n"})})]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-js",metastring:'title="sw.js"',children:"import '@uppy/golden-retriever/lib/ServiceWorker.js';\n"})}),"\n"]}),"\n",(0,s.jsxs)(r.li,{children:["\n",(0,s.jsx)(r.p,{children:"Register it in your app\u2019s entry point:"}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-js",children:"// you app.js entry point\nuppy.use(GoldenRetriever, { serviceWorker: true });\n\nif ('serviceWorker' in navigator) {\n\tnavigator.serviceWorker\n\t\t.register('/sw.js', { type: 'module' }) // path to your bundled service worker which imports GoldenRetriever service worker\n\t\t.then((registration) => {\n\t\t\tconsole.log(\n\t\t\t\t'ServiceWorker registration successful with scope: ',\n\t\t\t\tregistration.scope,\n\t\t\t);\n\t\t})\n\t\t.catch((error) => {\n\t\t\tconsole.log(`Registration failed with ${error}`);\n\t\t});\n}\n"})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(r.p,{children:"Voil\xe0, that\u2019s it. Happy retrieving!"}),"\n",(0,s.jsx)(r.h2,{id:"api",children:"API"}),"\n",(0,s.jsx)(r.h3,{id:"options",children:"Options"}),"\n",(0,s.jsx)(r.h4,{id:"id",children:(0,s.jsx)(r.code,{children:"id"})}),"\n",(0,s.jsxs)(r.p,{children:["A unique identifier for this plugin (",(0,s.jsx)(r.code,{children:"string"}),", default: ",(0,s.jsx)(r.code,{children:"'GoldenRetriever'"}),")."]}),"\n",(0,s.jsx)(r.h4,{id:"expires",children:(0,s.jsx)(r.code,{children:"expires"})}),"\n",(0,s.jsxs)(r.p,{children:["How long to store metadata and files for. Used for ",(0,s.jsx)(r.code,{children:"IndexedDB"})," and, when\n",(0,s.jsx)(r.code,{children:"window.indexedDB"})," is not available, ",(0,s.jsx)(r.code,{children:"LocalStorage"})," (",(0,s.jsx)(r.code,{children:"number"}),", default:\n",(0,s.jsx)(r.code,{children:"24 * 60 * 60 * 1000"})," // 24 hours)."]}),"\n",(0,s.jsx)(r.h4,{id:"serviceworker",children:(0,s.jsx)(r.code,{children:"serviceWorker"})}),"\n",(0,s.jsxs)(r.p,{children:["Whether to enable ",(0,s.jsx)(r.code,{children:"Service Worker"})," storage (",(0,s.jsx)(r.code,{children:"boolean"}),", default: ",(0,s.jsx)(r.code,{children:"false"}),")."]})]})}function x(e={}){const{wrapper:r}={...(0,t.R)(),...e.components};return r?(0,s.jsx)(r,{...e,children:(0,s.jsx)(u,{...e})}):u(e)}},65171:(e,r,n)=>{n.d(r,{A:()=>a});var i=n(96540),s=n(88149),t=n(27293),o=n(4476),l=n(74848);const{rE:d}=o;
1function a({children:e,uppyCssName:r="uppy.min.css",uppyJsName:n="uppy.min.mjs"}){let o=[];i.Children.toArray(e).forEach(e=>{o=[...o,...String(e).trim().split("\n").map(e=>e.trim())]});const a=o.map(e=>` ${e}`).join("\n"),c=`https://releases.transloadit.com/uppy/v${d}/${n}`,h=`\x3c!-- 1. Add CSS to \`<head>\` --\x3e\n<link href="https://releases.transloadit.com/uppy/v${d}/${r}" rel="stylesheet">\n\n\x3c!-- 2. Initialize --\x3e\n<div id="uppy"></div>\n\n<script type="module">\n${a.replace(/{{UPPY_JS_URL}}/g,c)}\n<\/script>\n`;return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsxs)(t.A,{type:"caution",children:[(0,l.jsx)("p",{children:"The bundle consists of most Uppy plugins, so this method is not recommended for production, as your users will have to download all plugins when you are likely using only a few."}),(0,l.jsx)("p",{children:"It can be useful to speed up your development environment, so don't hesitate to use it to get you started."})]}),(0,l.jsx)(s.A,{language:"html",children:h})]})}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.