feat(v2): Add <Root> theme element

packages/docusaurus/src/client/App.tsx

@@ -17,6 +17,7 @@ import renderRoutes from './exports/renderRoutes';
 import DocusaurusContext from './exports/context';
 import PendingNavigation from './PendingNavigation';
 import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import Root from '@theme/Root';
 
 import './client-lifecycles-dispatcher';
 
@@ -37,10 +38,12 @@ function App(): JSX.Element {
         codeTranslations,
         isClient,
       }}>
-      <BaseUrlIssueBanner />
-      <PendingNavigation routes={routes}>
-        {renderRoutes(routes)}
-      </PendingNavigation>
+      <Root>
+        <BaseUrlIssueBanner />
+        <PendingNavigation routes={routes}>
+          {renderRoutes(routes)}
+        </PendingNavigation>
+      </Root>
     </DocusaurusContext.Provider>
   );
 }

packages/docusaurus/src/client/theme-fallback/Root/index.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+// Wrapper at the very top of the app, that is applied constantly
+// and does not depend on current route (unlike the layout)
+//
+// Gives the opportunity to add stateful providers on top of the app
+// and these providers won't reset state when we navigate
+//
+// See https://github.com/facebook/docusaurus/issues/3919
+function Root({children}) {
+  return <>{children}</>;
+}
+
+export default Root;

website/docs/using-themes.md

@@ -71,7 +71,30 @@ And if you want to use Bootstrap styling, you can swap out the theme with `theme
 }
 ```
 
-The content plugin remains the same and the only thing you need to change is the theme.
+## Wrapper your site with `<Root>`
+
+A `<Root>` theme component is rendered at the very top of your Docusaurus site.
+
+It allows you to wrap your site with additional logic, by creating a file at `website/src/theme/Root.js`:
+
+```js title="website/src/theme/Root.js"
+import React from 'react';
+
+// Default implementation, that you can customize
+function Root({children}) {
+  return <>{children}</>;
+}
+
+export default Root;
+```
+
+This component is applied above the router and the theme `<Layout>`, and will **never unmount**.
+
+:::tip
+
+Use this component render React Context providers and global stateful logic.
+
+:::
 
 ## Swizzling theme components