Instructions for converting storage.

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)

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.

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