UI: Prefer importing <RootProvider /> from fumadocs-ui/provider/<framework>

.changeset/ninety-lamps-dress.md

@@ -0,0 +1,8 @@
+---
+'fumadocs-ui': patch
+---
+
+**Prefer importing `<RootProvider />` from `fumadocs-ui/provider/<framework>`**
+
+- Old `fumadocs-ui/provider` will be kept, as it's used by majority of previous projects.
+- New guides & templates will follow the new recommendation.

apps/docs/content/docs/ui/(ui)/layouts/root-provider.mdx

@@ -8,8 +8,10 @@ for search dialog. It should be located at the root layout.
 
 ## Usage
 
+Import it according to your React.js framework:
+
 ```jsx tab="Next.js"
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 
 export default function Layout({ children }) {
   return (
@@ -22,8 +24,45 @@ export default function Layout({ children }) {
 }
 ```
 
-```jsx tab="Others"
-import { RootProvider } from 'fumadocs-ui/provider/base';
+```jsx tab="React Router"
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
+
+export function Layout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```jsx tab="Tanstack"
+import {
+  HeadContent,
+  Scripts,
+} from '@tanstack/react-router';
+import { RootProvider } from 'fumadocs-ui/provider/tanstack';
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body className="flex flex-col min-h-screen">
+        <RootProvider>{children}</RootProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+```
+
+```jsx tab="Waku"
+import { RootProvider } from 'fumadocs-ui/provider/waku';
 
 export default function Layout({ children }) {
   return (

apps/docs/content/docs/ui/(ui)/theme.mdx

@@ -46,7 +46,7 @@ RTL (Right-to-left) layout is supported.
 To enable RTL, set the `dir` prop to `rtl` in body and root provider (required for Radix UI).
 
 ```tsx
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/<framework>';
 import type { ReactNode } from 'react';
 
 export default function RootLayout({ children }: { children: ReactNode }) {

apps/docs/content/docs/ui/internationalization/next.mdx

@@ -57,7 +57,7 @@ Create a `/app/[lang]` folder, and move your pages/layouts into it, except route
 Provide UI translations and other config to `<RootProvider />`, the English translations are used when `translations` is not specified.
 
 ```tsx title="app/[lang]/layout.tsx"
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';
 

apps/docs/content/docs/ui/manual-installation/next.mdx

@@ -32,7 +32,7 @@ Create a file for MDX components:
 Wrap the entire application inside [Root Provider](/docs/ui/layouts/root-provider), and add required styles to `body`.
 
 ```tsx title="app/layout.tsx"
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import type { ReactNode } from 'react';
 
 export default function Layout({ children }: { children: ReactNode }) {

apps/docs/content/docs/ui/manual-installation/react-router.mdx

@@ -58,8 +58,7 @@ Wrap your entire app under Fumadocs providers:
 
 ```tsx title="root.tsx"
 import { Links, Meta, Scripts, ScrollRestoration } from 'react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 import './app.css';
 
 export function Layout({ children }: { children: React.ReactNode }) {
@@ -72,10 +71,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        {/* [!code ++:3] */}
-        <ReactRouterProvider>
-          <RootProvider>{children}</RootProvider>
-        </ReactRouterProvider>
+        {/* [!code ++] */}
+        <RootProvider>{children}</RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

apps/docs/content/docs/ui/manual-installation/tanstack-start.mdx

@@ -51,8 +51,7 @@ import {
   Scripts,
 } from '@tanstack/react-router';
 import * as React from 'react';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
+import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 
 export const Route = createRootRoute({
   component: RootComponent,
@@ -73,10 +72,8 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         <HeadContent />
       </head>
       <body className="flex flex-col min-h-screen">
-        {/* [!code ++:3] */}
-        <TanstackProvider>
-          <RootProvider>{children}</RootProvider>
-        </TanstackProvider>
+        {/* [!code ++] */}
+        <RootProvider>{children}</RootProvider>
         <Scripts />
       </body>
     </html>

apps/docs/content/docs/ui/search/.shared.mdx

@@ -1,12 +1,11 @@
 ### Replace Search Dialog
 
-Replace the search dialog with yours from `<RootProvider />`:
+Replace the search dialog with yours from [`<RootProvider />`](/docs/ui/root-provider):
 
 ```tsx
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/<framework>';
 // [!code ++]
 import SearchDialog from '@/components/search';
-import type { ReactNode } from 'react';
 
 <RootProvider
   // [!code ++:3]
@@ -22,7 +21,7 @@ If it was in a server component, you would need a separate client component for
 
 ```tsx tab="provider.tsx"
 'use client';
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/<framework>';
 import SearchDialog from '@/components/search';
 import type { ReactNode } from 'react';
 

apps/docs/content/docs/ui/search/index.mdx

@@ -10,7 +10,7 @@ You can customise some configurations from root provider.
 For example, to disable search UI:
 
 ```tsx title="app/layout.tsx"
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/<framework>';
 import type { ReactNode } from 'react';
 
 export default function Layout({ children }: { children: ReactNode }) {
@@ -35,7 +35,7 @@ export default function Layout({ children }: { children: ReactNode }) {
 Customise the hot keys to trigger search dialog, by default it's <kbd>⌘</kbd> <kbd>K</kbd> or <kbd>Ctrl</kbd> <kbd>K</kbd>.
 
 ```tsx
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/<framework>';
 
 <RootProvider
   search={{

examples/content-collections/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import 'fumadocs-ui/style.css';
 import { Inter } from 'next/font/google';
 import type { ReactNode } from 'react';

examples/i18n/app/[lang]/layout.tsx

@@ -1,5 +1,5 @@
 import 'fumadocs-ui/style.css';
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import { Inter } from 'next/font/google';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';

examples/marble-cms/app/layout.tsx

@@ -1,5 +1,5 @@
 import '@/app/global.css';
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import { Inter } from 'next/font/google';
 
 const inter = Inter({

examples/next-mdx/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import './global.css';
 import { Inter } from 'next/font/google';
 

examples/obsidian/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import './global.css';
 import { Inter } from 'next/font/google';
 

examples/openapi/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import './global.css';
 import { Inter, JetBrains_Mono } from 'next/font/google';
 import type { ReactNode } from 'react';

examples/python/app/layout.tsx

@@ -1,5 +1,5 @@
 import './global.css';
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import { Inter } from 'next/font/google';
 import type { ReactNode } from 'react';
 

examples/react-router-i18n/app/root.tsx

@@ -7,8 +7,7 @@ import {
   ScrollRestoration,
   useParams,
 } from 'react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 import type { Route } from './+types/root';
 import './app.css';
 import type { Translations } from 'fumadocs-ui/i18n';
@@ -54,17 +53,15 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        <ReactRouterProvider>
-          <RootProvider
-            i18n={{
-              locale: lang,
-              locales,
-              translations: { cn }[lang],
-            }}
-          >
-            {children}
-          </RootProvider>
-        </ReactRouterProvider>
+        <RootProvider
+          i18n={{
+            locale: lang,
+            locales,
+            translations: { cn }[lang],
+          }}
+        >
+          {children}
+        </RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

examples/react-router/app/root.tsx

@@ -6,8 +6,7 @@ import {
   Scripts,
   ScrollRestoration,
 } from 'react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 import type { Route } from './+types/root';
 import './app.css';
 
@@ -34,9 +33,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        <ReactRouterProvider>
-          <RootProvider>{children}</RootProvider>
-        </ReactRouterProvider>
+        <RootProvider>{children}</RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

examples/remote-mdx/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import 'fumadocs-ui/style.css';
 import { Inter } from 'next/font/google';
 import type { ReactNode } from 'react';

examples/tanstack-start-i18n/src/routes/__root.tsx

@@ -1,4 +1,3 @@
-/// <reference types="vite/client" />
 import {
   createRootRoute,
   HeadContent,
@@ -8,8 +7,7 @@ import {
 } from '@tanstack/react-router';
 import * as React from 'react';
 import appCss from '@/styles/app.css?url';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
+import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';
 
@@ -61,9 +59,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         <HeadContent />
       </head>
       <body className="flex flex-col min-h-screen">
-        <TanstackProvider>
-          <RootProvider i18n={provider(lang)}>{children}</RootProvider>
-        </TanstackProvider>
+        <RootProvider i18n={provider(lang)}>{children}</RootProvider>
         <Scripts />
       </body>
     </html>

examples/tanstack-start-i18n/tsconfig.json

@@ -14,6 +14,7 @@
     "allowJs": true,
     "forceConsistentCasingInFileNames": true,
     "baseUrl": ".",
+    "types": ["vite/client"],
     "paths": {
       "@/*": ["./src/*"]
     },

examples/tanstack-start/src/routes/__root.tsx

@@ -1,4 +1,3 @@
-/// <reference types="vite/client" />
 import {
   createRootRoute,
   HeadContent,
@@ -7,8 +6,7 @@ import {
 } from '@tanstack/react-router';
 import * as React from 'react';
 import appCss from '@/styles/app.css?url';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
+import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 
 export const Route = createRootRoute({
   head: () => ({
@@ -44,9 +42,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         <HeadContent />
       </head>
       <body className="flex flex-col min-h-screen">
-        <TanstackProvider>
-          <RootProvider>{children}</RootProvider>
-        </TanstackProvider>
+        <RootProvider>{children}</RootProvider>
         <Scripts />
       </body>
     </html>

examples/tanstack-start/tsconfig.json

@@ -7,6 +7,7 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["vite/client"],
     "isolatedModules": true,
     "resolveJsonModule": true,
     "skipLibCheck": true,

examples/waku-i18n/src/components/provider.tsx

@@ -1,7 +1,6 @@
 'use client';
 import type { ReactNode } from 'react';
-import { WakuProvider } from 'fumadocs-core/framework/waku';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/waku';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18n } from '@/lib/i18n';
 import { useRouter } from 'waku/router/client';
@@ -22,10 +21,8 @@ export function Provider({ children }: { children: ReactNode }) {
   const router = useRouter();
 
   return (
-    <WakuProvider>
-      <RootProvider i18n={provider(router.path.split('/')[1])}>
-        {children}
-      </RootProvider>
-    </WakuProvider>
+    <RootProvider i18n={provider(router.path.split('/')[1])}>
+      {children}
+    </RootProvider>
   );
 }

examples/waku-openapi/src/components/provider.tsx

@@ -1,12 +1,7 @@
 'use client';
 import type { ReactNode } from 'react';
-import { WakuProvider } from 'fumadocs-core/framework/waku';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/waku';
 
 export function Provider({ children }: { children: ReactNode }) {
-  return (
-    <WakuProvider>
-      <RootProvider>{children}</RootProvider>
-    </WakuProvider>
-  );
+  return <RootProvider>{children}</RootProvider>;
 }

examples/waku/src/components/provider.tsx

@@ -1,12 +1,7 @@
 'use client';
 import type { ReactNode } from 'react';
-import { WakuProvider } from 'fumadocs-core/framework/waku';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/waku';
 
 export function Provider({ children }: { children: ReactNode }) {
-  return (
-    <WakuProvider>
-      <RootProvider>{children}</RootProvider>
-    </WakuProvider>
-  );
+  return <RootProvider>{children}</RootProvider>;
 }

packages/create-app/template/+next+tailwindcss/app/layout.tsx

@@ -1,5 +1,5 @@
 import '@/app/global.css';
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import { Inter } from 'next/font/google';
 
 const inter = Inter({

packages/create-app/template/+next/app/layout.tsx

@@ -1,4 +1,4 @@
-import { RootProvider } from 'fumadocs-ui/provider';
+import { RootProvider } from 'fumadocs-ui/provider/next';
 import 'fumadocs-ui/style.css';
 import { Inter } from 'next/font/google';
 

packages/create-app/template/react-router/app/root.tsx

@@ -6,8 +6,7 @@ import {
   Scripts,
   ScrollRestoration,
 } from 'react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 import type { Route } from './+types/root';
 import './app.css';
 
@@ -34,9 +33,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        <ReactRouterProvider>
-          <RootProvider>{children}</RootProvider>
-        </ReactRouterProvider>
+        <RootProvider>{children}</RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

packages/create-app/template/tanstack-start/src/routes/__root.tsx

@@ -1,4 +1,3 @@
-/// <reference types="vite/client" />
 import {
   createRootRoute,
   HeadContent,
@@ -7,8 +6,7 @@ import {
 } from '@tanstack/react-router';
 import * as React from 'react';
 import appCss from '@/styles/app.css?url';
-import { RootProvider } from 'fumadocs-ui/provider/base';
-import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
+import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 
 export const Route = createRootRoute({
   head: () => ({
@@ -44,9 +42,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         <HeadContent />
       </head>
       <body className="flex flex-col min-h-screen">
-        <TanstackProvider>
-          <RootProvider>{children}</RootProvider>
-        </TanstackProvider>
+        <RootProvider>{children}</RootProvider>
         <Scripts />
       </body>
     </html>

packages/create-app/template/tanstack-start/tsconfig.json

@@ -7,6 +7,7 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["vite/client"],
     "isolatedModules": true,
     "resolveJsonModule": true,
     "skipLibCheck": true,

packages/create-app/template/waku/src/components/provider.tsx

@@ -1,12 +1,7 @@
 'use client';
 import type { ReactNode } from 'react';
-import { WakuProvider } from 'fumadocs-core/framework/waku';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/waku';
 
 export function Provider({ children }: { children: ReactNode }) {
-  return (
-    <WakuProvider>
-      <RootProvider>{children}</RootProvider>
-    </WakuProvider>
-  );
+  return <RootProvider>{children}</RootProvider>;
 }

packages/press/src/lib/root-layout.tsx

@@ -1,6 +1,5 @@
 'use client';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 import type { ReactNode } from 'react';
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
 
@@ -14,9 +13,7 @@ export function Layout({ children }: { children: ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        <ReactRouterProvider>
-          <RootProvider>{children}</RootProvider>
-        </ReactRouterProvider>
+        <RootProvider>{children}</RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

packages/press/src/routes/root/client.tsx

@@ -8,8 +8,7 @@ import {
   ScrollRestoration,
   useRouteError,
 } from 'react-router';
-import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
-import { RootProvider } from 'fumadocs-ui/provider/base';
+import { RootProvider } from 'fumadocs-ui/provider/react-router';
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
@@ -22,9 +21,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
       </head>
       <body className="flex flex-col min-h-screen">
-        <ReactRouterProvider>
-          <RootProvider>{children}</RootProvider>
-        </ReactRouterProvider>
+        <RootProvider>{children}</RootProvider>
         <ScrollRestoration />
         <Scripts />
       </body>

packages/ui/src/provider/index.tsx

@@ -1,17 +1,6 @@
 'use client';
 
-import { RootProvider as BaseProvider } from './base';
-import type { ComponentProps } from 'react';
-import { NextProvider } from 'fumadocs-core/framework/next';
-
-export function RootProvider(props: ComponentProps<typeof BaseProvider>) {
-  return (
-    <NextProvider>
-      <BaseProvider {...props}>{props.children}</BaseProvider>
-    </NextProvider>
-  );
-}
-
+export * from './next';
 export { useI18n, I18nLabel } from '@/contexts/i18n';
 export {
   SearchProvider,

packages/ui/src/provider/next.tsx

@@ -0,0 +1,12 @@
+'use client';
+import type { ComponentProps } from 'react';
+import { RootProvider as BaseProvider } from '@/provider/base';
+import { NextProvider } from 'fumadocs-core/framework/next';
+
+export function RootProvider(props: ComponentProps<typeof BaseProvider>) {
+  return (
+    <NextProvider>
+      <BaseProvider {...props}>{props.children}</BaseProvider>
+    </NextProvider>
+  );
+}

packages/ui/src/provider/react-router.tsx

@@ -0,0 +1,12 @@
+'use client';
+import type { ComponentProps } from 'react';
+import { RootProvider as BaseProvider } from '@/provider/base';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+
+export function RootProvider(props: ComponentProps<typeof BaseProvider>) {
+  return (
+    <ReactRouterProvider>
+      <BaseProvider {...props}>{props.children}</BaseProvider>
+    </ReactRouterProvider>
+  );
+}

packages/ui/src/provider/tanstack.tsx

@@ -0,0 +1,12 @@
+'use client';
+import type { ComponentProps } from 'react';
+import { RootProvider as BaseProvider } from '@/provider/base';
+import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
+
+export function RootProvider(props: ComponentProps<typeof BaseProvider>) {
+  return (
+    <TanstackProvider>
+      <BaseProvider {...props}>{props.children}</BaseProvider>
+    </TanstackProvider>
+  );
+}

packages/ui/src/provider/waku.tsx

@@ -0,0 +1,12 @@
+'use client';
+import type { ComponentProps } from 'react';
+import { RootProvider as BaseProvider } from '@/provider/base';
+import { WakuProvider } from 'fumadocs-core/framework/waku';
+
+export function RootProvider(props: ComponentProps<typeof BaseProvider>) {
+  return (
+    <WakuProvider>
+      <BaseProvider {...props}>{props.children}</BaseProvider>
+    </WakuProvider>
+  );
+}