diff --git a/site/en/docs/extensions/migrating/checklist/index.md b/site/en/docs/extensions/migrating/checklist/index.md index d35c6b20cd56..3cabbd35e97c 100644 --- a/site/en/docs/extensions/migrating/checklist/index.md +++ b/site/en/docs/extensions/migrating/checklist/index.md @@ -4,6 +4,7 @@ title: "Manifest V3 migration checklist" subhead: Keep track of your migration progress description: A quick reference for upgrading your extensions from Manifest V2 to Manifest V3. date: 2023-03-09 +updated: 2023-03-15 --- {% Partial 'extensions/mv3-support.md' %} @@ -35,6 +36,7 @@ Before beginning, read about the [differences between background scripts and ext * [Update the "background" field in the manifest](/docs/extensions/migrating/to-service-workers/#update-bg-field) * [Move DOM and window calls to an offscreen document](/docs/extensions/migrating/to-service-workers/#move-dom-and-window) +* [Convert localStorage to chrome.storage.local](/docs/extensions/migrating/to-service-workers/#convert-localstorage) * [Register listeners synchronously](/docs/extensions/migrating/to-service-workers/#register-listeners) * [Replace calls to `XMLHttpRequest()` with global `fetch()`](/docs/extensions/migrating/to-service-workers/#replace-xmlhttprequest). * [Persist states](/docs/extensions/migrating/to-service-workers/#persist-states) diff --git a/site/en/docs/extensions/migrating/to-service-workers/index.md b/site/en/docs/extensions/migrating/to-service-workers/index.md index ece978510599..9ca944af35da 100644 --- a/site/en/docs/extensions/migrating/to-service-workers/index.md +++ b/site/en/docs/extensions/migrating/to-service-workers/index.md @@ -4,7 +4,7 @@ title: Migrate to a service worker subhead: 'Replacing background or event pages with a service worker' description: 'A service worker enables extensions to run only when needed, saving resources.' date: 2023-03-09 -updated: 2023-04-14 +updated: 2023-05-01 --- {% Partial 'extensions/mv3-support.md' %} @@ -105,6 +105,13 @@ document.execCommand('copy'); Communicate between offscreen documents and extension service workers using [message passing](/docs/extensions/mv3/messaging/). +## Convert localStorage to chrome.storage.local {: #convert-localstorage } + +The web platform's [`Storage`](https://developer.mozilla.org/docs/Web/API/Storage) interface (accessible from `window.localStorage`) cannot be used in a service worker. To address this: + +1. Move its calls to an [offscreen document](/docs/extensions/reference/offscreen/). +1. (Optional) Replace it with calls to the [`chrome.storage.local`](/docs/extensions/reference/storage/#property-local) namespace. For details, see [the instructions](/docs/extensions/reference/storage/#can-extensions-use-storage). + ## Register listeners synchronously {: #register-listeners } Registering a listener asynchronously (for example inside a promise or callback) is not guaranteed to work in Manifest V3. Consider the following code. diff --git a/site/en/docs/extensions/reference/storage/index.md b/site/en/docs/extensions/reference/storage/index.md index 8f4f323c3f97..f1eafe61a196 100644 --- a/site/en/docs/extensions/reference/storage/index.md +++ b/site/en/docs/extensions/reference/storage/index.md @@ -4,7 +4,7 @@ api: storage ## Overview {: #overview } -The Storage API provides an extension-specific way to persist user data and state. It's similar to the web platform's storage APIs ([IndexedDB][mdn-indexeddb], and [localStorage][mdn-localstorage]), but was designed to meet the storage needs of extensions. The following are a few key features: +The Storage API provides an extension-specific way to persist user data and state. It's similar to the web platform's storage APIs ([IndexedDB][mdn-indexeddb], and [Storage][mdn-storage]), but was designed to meet the storage needs of extensions. The following are a few key features: - All extension contexts, including the extension service worker and content scripts have access to the Storage API. - The JSON serializable values are stored as object properties. @@ -15,14 +15,21 @@ The Storage API provides an extension-specific way to persist user data and stat {% Details %} {% DetailsSummary %} -💡 Can extensions use the WebStorage API? +💡 Can extensions use the Storage API? {% endDetailsSummary %} -Even though extensions can access [`Window.localStorage`][mdn-localstorage] in some contexts (popup and other HTML pages), it is not recommended for the following reasons: +Even though extensions can use the [`Storage`][mdn-storage] interface (accessible from `window.localStorage`) in some contexts (popup and other HTML pages), it is not recommended for the following reasons: -- The extension's service worker cannot access `Window.localStorage`. -- Content scripts share the `Window.localStorage` of the host page. -- Data saved to `Window.localStorage` is lost when the user clears their browsing history. +- Extension's service worker cannot access `Storage`. +- Content scripts share storage with the host page. +- Data saved using the `Storage` interface is lost when the user clears their browsing history. + + +1. Create an offscreen document with a conversion routine and an [`onMessage`][on-message] handler. +1. Add a conversion routine to an offscreen document. +1. In the extension service worker check `chrome.storage` for your data. +1. If your data isn't found, [create][create-offscreen] an offscreen document and call [`sendMessage()`][send-message] to start the conversion routine. +1. Inside the offscreen document's `onMessage` handler, call the conversion routine. {% endDetails %} @@ -238,16 +245,20 @@ To see other demos of the Storage API, explore any of the following examples: - [Global search extension][gh-global-context-search]. - [Water alarm extension][gh-water-alarm]. +[create-offscreen]: /docs/extensions/reference/offscreen/#method-createDocument [doc-manifest]: /docs/extensions/mv3/manifest [gh-global-context-search]: https://github.com/GoogleChrome/chrome-extensions-samples/tree/17956f44b6f04d28407a4b7eee428611affd4fab/api/contextMenus/global_context_search [gh-water-alarm]: https://github.com/GoogleChrome/chrome-extensions-samples/tree/17956f44b6f04d28407a4b7eee428611affd4fab/examples/water_alarm_notification [incognito]: /docs/extensions/mv2/manifest/incognito [manifest-storage]: /docs/extensions/mv3/manifest/storage [mdn-indexeddb]: https://developer.mozilla.org/docs/Web/API/Window/indexeddb -[mdn-localstorage]: https://developer.mozilla.org/docs/Web/API/Window/localStorage +[mdn-storage]: https://developer.mozilla.org/docs/Web/API/Storage [method-access-level]: #method-StorageArea-setAccessLevel +[offscreen-document]: /docs/extensions/reference/offscreen/ +[on-message]: /docs/extensions/reference/runtime/#event-onMessage [options-page]: https://developer.chrome.com/docs/extensions/mv3/options/ [prop-local]: #property-local [prop-sync]: #property-sync [prop-session]: #property-session [prop-managed]: #property-managed +[send-message]: /docs/extensions/reference/runtime/#method-sendMessage