feat(core): site storage config options (experimental)

[slorber]

Motivation

This introduces new site config options to let users control the default browser storage behavior of a Docusaurus site.

Note: our themes respect that config, but third-party themes are not forced to, and it's only a default that can be ignored on a case-by-case basis.

It is useful to apply a namespace to browser storage keys, to avoid storage key conflicts on the same domain:

• Docusaurus devs might work on multiple sites locally (all under http://localhost:3000)
• Docusaurus sites might be hosted on the same domain using /baseUrl/ (https://example.com/site1/ + https://example.com/site2/). This is notably the case at Meta.

While we work on this, it's also a good opportunity to let users decide between localStorage or sessionStorage for browser persistence.

For retro-compatibility reasons, we can't apply a namespace by default in v3, so it has to be turned on through options.

This is a good opportunity for Docusaurus to introduce Future Flags similar to what the Remix framework does. We can ship opt-in breaking changes that we might turn on by default on upcoming major versions.

The config for this new feature:

export default {
  future: {
    experimental_storage: {
      type: "localStorage",
      namespace: "my-namespace-key-suffix",
    }
  }
}

For convenience, it's possible to use config.future.experimental_storage.namespace = true.
In this case, we'll compute a 3-char hash based on your https://siteUrl.com/baseUrl/siteUrl/ (ie your theme storage key become theme-x7j)
We may turn this on by default in Docusaurus v4 (breaking change), with an option to revert.

For now, this API is experimental until we get feedback from internal usage at Meta. We might refactor it in minor versions according to feedback.

Test Plan

CI + preview + internal rollout at Meta

When namespacing is on, storage keys should have a suffix:

Test links

https://deploy-preview-10121--docusaurus-2.netlify.app/

Migration strategy

The default/classic Docusaurus theme stores the following keys in localStorage:

• Theme
• Announcement bar state
• Docs preferred version (last version selected, displayed in the dropdown on home/blog pages)

It shouldn't be a big deal to have these stored values being reset, but if you want to turn on storage namspacing without disrupting the user experience, you can migrate storage keys with a client module script like this one:

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
import SiteStorage from '@generated/site-storage';

if (ExecutionEnvironment.canUseDOM) {
  const migrateStorageKey = (key: string) => {
    const value = localStorage.getItem(key);
    if (value !== null && SiteStorage.namespace) {
      const newKey = `${key}${SiteStorage.namespace}`;
      console.log(`Migrating storage key [ ${key} => ${newKey} ], value=${value}`);
      localStorage.setItem(newKey, value);
      localStorage.removeItem(key);
    }
  };

  const storageKeys = [
    'theme',
    'docusaurus.announcement.id',
    'docusaurus.announcement.dismiss',
    // You might need more if you have multiple versioned docs
    'docs-preferred-version-default', 
    // "groupId"s you might use with <Tabs> component
    'docusaurus.tab.npm2yarn',
  ];
  storageKeys.forEach(migrateStorageKey);
}

Note that:

• If you had storage key conflicts, it's probably not really useful to migrate keys considering your keys were already shared and produced issues. It might be better to reset them? 🤷‍♂️
• Third-party plugins might also use localStorage. They probably don't respect (yet) your namespace since it's a new feature and they'd need to add support for it.

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	e92ab05
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/663e12cfda5c7700086bbaba
😎 Deploy Preview	https://deploy-preview-10121--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 57	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 86	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 68	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 64	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 69	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 76	🟢 100	🟢 100	🟢 90	🟠 88	Report

[github-actions]

Size Change: +687 B (+0.04%)

Total Size: 1.71 MB

Filename	Size	Change
website/.docusaurus/docusaurus.config.mjs	26.9 kB	+109 B (+0.41%)
website/build/assets/js/main.********.js	853 kB	+567 B (+0.07%)

ℹ️ View Unchanged

Filename	Size	Change
website/.docusaurus/codeTranslations.json	2 B	0 B
website/.docusaurus/globalData.json	107 kB	0 B
website/.docusaurus/i18n.json	930 B	0 B
website/.docusaurus/registry.js	275 kB	0 B
website/.docusaurus/routes.js	179 kB	0 B
website/.docusaurus/routesChunkNames.json	119 kB	0 B
website/.docusaurus/site-metadata.json	2.17 kB	0 B
website/build/assets/css/styles.********.css	112 kB	0 B
website/build/index.html	38.1 kB	+11 B (+0.03%)

_{compressed-size-action}