Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 9 commits into from
May 10, 2024

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented May 9, 2024

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:

CleanShot 2024-05-09 at 19 47 00

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.

@slorber slorber added the pr: new feature This PR adds a new API or behavior. label May 9, 2024
@slorber slorber requested a review from Josh-Cena as a code owner May 9, 2024 17:38
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label May 9, 2024
Copy link

netlify bot commented May 9, 2024

[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...

QR Code

Use your smartphone camera to open QR code link.

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

Copy link

github-actions bot commented May 9, 2024

⚡️ 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

Copy link

github-actions bot commented May 9, 2024

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

@slorber slorber merged commit 620e463 into main May 10, 2024
31 checks passed
@slorber slorber deleted the slorber/storage-config branch May 10, 2024 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants