Skip to content

Commit

Permalink
[AppProvider] Use unique names for framework specific AppProviders (#…
Browse files Browse the repository at this point in the history 
…4553)
  • Loading branch information
@apedroferreira
apedroferreira authored Jan 7, 2025
1 parent 1d7dc89 commit 47e55ed
Show file tree
Hide file tree
Showing 63 changed files with 232 additions and 198 deletions.
26 changes: 13 additions & 13 deletions docs/data/toolpad/core/components/app-provider/app-provider.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,30 +26,30 @@ In the following example, an `AppProvider` component wrapping the page provides

## Next.js

The `AppProvider` for Next.js applications includes some Next.js integrations out-of-the-box.
The `NextAppProvider` includes some Next.js integrations out-of-the-box.

By using the specific `AppProvider` for Next.js you do not have to manually configure the integration between some Toolpad features and the corresponding Next.js features (such as routing), making the integration automatic and seamless.
By using the specific `NextAppProvider` you do not have to manually configure the integration between some Toolpad features and the corresponding Next.js features (such as routing), making the integration automatic and seamless.

```tsx
import { AppProvider } from '@toolpad/core/nextjs';
import { NextAppProvider } from '@toolpad/core/nextjs';
```

### Next.js App Router

When using the **Next.js App Router**, the most typical file where to import and use `AppProvider` will be at the top level `layout.tsx` file that defines the layout for all the application pages.
When using the **Next.js App Router**, the most typical file where to import and use `NextAppProvider` is the top level `layout.tsx` file that defines the layout for all the application pages.

```tsx
// app/layout.tsx

import { AppProvider } from '@toolpad/core/nextjs';
import { NextAppProvider } from '@toolpad/core/nextjs';

export default function Layout(props) {
const { children } = props;

return (
<html lang="en">
<body>
<AppProvider>{children}</AppProvider>
<NextAppProvider>{children}</NextAppProvider>
</body>
</html>
);
Expand All @@ -58,32 +58,32 @@ export default function Layout(props) {

### Next.js Pages Router

When using the **Next.js Pages Router**, the most typical file where to import and use `AppProvider` in order to wrap every page in the application will be the `pages/_app.tsx` file.
When using the **Next.js Pages Router**, the most typical file where to import and use `NextAppProvider` in order to wrap every page in the application is the `pages/_app.tsx` file.

```tsx
// pages/_app.tsx

import { AppProvider } from '@toolpad/core/nextjs';
import { NextAppProvider } from '@toolpad/core/nextjs';

export default function App(props) {
const { Component, pageProps } = props;

return (
<AppProvider>
<NextAppProvider>
<Component {...pageProps} />
</AppProvider>
</NextAppProvider>
);
}
```

## Client-side routing

The `AppProvider` for React Router includes routing out-of-the-box for projects using [react-router-dom](https://www.npmjs.com/package/react-router-dom).
The `ReactRouterAppProvider` includes routing out-of-the-box for projects using [react-router](https://www.npmjs.com/package/react-router).

This specific `AppProvider` is recommended when building single-page applications with tools such as [Vite](https://vite.dev/), as you do not have to manually configure your app routing, making the integration automatic and seamless.
This specific `ReactRouterAppProvider` is recommended when building single-page applications with tools such as [Vite](https://vite.dev/), as you do not have to manually configure your app routing, making the integration automatic and seamless.

```tsx
import { AppProvider } from '@toolpad/core/react-router-dom';
import { ReactRouterAppProvider } from '@toolpad/core/react-router';
```

## Theming
Expand Down
8 changes: 4 additions & 4 deletions docs/data/toolpad/core/integrations/ReactRouter.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ import { createTheme } from '@mui/material/styles';
import Typography from '@mui/material/Typography';
import DashboardIcon from '@mui/icons-material/Dashboard';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
import { createMemoryRouter, RouterProvider, Outlet } from 'react-router-dom';
import { AppProvider } from '@toolpad/core/react-router-dom';
import { createMemoryRouter, RouterProvider, Outlet } from 'react-router';
import { ReactRouterAppProvider } from '@toolpad/core/react-router';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import { PageContainer } from '@toolpad/core/PageContainer';

Expand Down Expand Up @@ -67,14 +67,14 @@ function App(props) {
const { window } = props;

return (
<AppProvider
<ReactRouterAppProvider
navigation={NAVIGATION}
branding={BRANDING}
theme={demoTheme}
window={window}
>
<Outlet />
</AppProvider>
</ReactRouterAppProvider>
);
}

Expand Down
8 changes: 4 additions & 4 deletions docs/data/toolpad/core/integrations/ReactRouter.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ import { createTheme } from '@mui/material/styles';
import Typography from '@mui/material/Typography';
import DashboardIcon from '@mui/icons-material/Dashboard';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
import { createMemoryRouter, RouterProvider, Outlet } from 'react-router-dom';
import { AppProvider } from '@toolpad/core/react-router-dom';
import { createMemoryRouter, RouterProvider, Outlet } from 'react-router';
import { ReactRouterAppProvider } from '@toolpad/core/react-router';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import { PageContainer } from '@toolpad/core/PageContainer';
import type { Navigation } from '@toolpad/core/AppProvider';
Expand Down Expand Up @@ -67,14 +67,14 @@ function App(props: { window?: Window }) {
const { window } = props;

return (
<AppProvider
<ReactRouterAppProvider
navigation={NAVIGATION}
branding={BRANDING}
theme={demoTheme}
window={window}
>
<Outlet />
</AppProvider>
</ReactRouterAppProvider>
);
}

Expand Down
12 changes: 6 additions & 6 deletions docs/data/toolpad/core/integrations/nextjs-approuter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,29 +26,29 @@ yarn add install @mui/material-nextjs @emotion/cache

</codeblock>

## Wrap your application with `AppProvider`
## Wrap your application with `NextAppProvider`

In your root layout file (for example, `app/layout.tsx`), wrap your application with the `AppProvider`:
In your root layout file (for example, `app/layout.tsx`), wrap your application with the `NextAppProvider`:

```tsx title="app/layout.tsx"
import { AppProvider } from '@toolpad/core/AppProvider';
import { NextAppProvider } from '@toolpad/core/nextjs';
import LinearProgress from '@mui/material/LinearProgress';
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<AppRouterCacheProvider options={{ enableCssLayer: true }}>
<React.Suspense fallback={<LinearProgress />}>
<AppProvider navigation={NAVIGATION} branding={BRANDING}>
<NextAppProvider navigation={NAVIGATION} branding={BRANDING}>
{children}
</AppProvider>
</NextAppProvider>
</React.Suspense>
</AppRouterCacheProvider>
);
}
```

You can find details on the `AppProvider` props on the [AppProvider](/toolpad/core/react-app-provider/) page.
You can find details on the `NextAppProvider` props on the [AppProvider](/toolpad/core/react-app-provider/) page.

:::info
The `AppRouterCacheProvider` component is not required to use Toolpad Core, but it's recommended to use it to ensure that the styles are appended to the `<head>` and not rendering in the `<body>`.
Expand Down
16 changes: 8 additions & 8 deletions docs/data/toolpad/core/integrations/nextjs-pagesrouter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,13 @@ yarn add install @mui/material-nextjs @emotion/cache

</codeblock>

## Wrap your application with `AppProvider`
## Wrap your application with `NextAppProvider`

In your root layout file (for example, `pages/_app.tsx`), wrap your application with the `AppProvider`:
In your root layout file (for example, `pages/_app.tsx`), wrap your application with the `NextAppProvider`:

```tsx title="pages/_app.tsx"
import * as React from 'react';
import { AppProvider } from '@toolpad/core/nextjs';
import { NextAppProvider } from '@toolpad/core/nextjs';
import { PageContainer } from '@toolpad/core/PageContainer';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import Head from 'next/head';
Expand Down Expand Up @@ -63,13 +63,13 @@ export default function App({ Component }: { Component: React.ElementType }) {
<Head>
<meta name="viewport" content="initial-scale=1, width=device-width" />
</Head>
<AppProvider navigation={NAVIGATION} branding={BRANDING}>
<NextAppProvider navigation={NAVIGATION} branding={BRANDING}>
<DashboardLayout>
<PageContainer>
<Component />
</PageContainer>
</DashboardLayout>
</AppProvider>
</NextAppProvider>
</AppCacheProvider>
);
}
Expand Down Expand Up @@ -221,7 +221,7 @@ Modify `_app.tsx` to include the `authentication` prop and other helpers:

```tsx title="pages/_app.tsx"
import * as React from 'react';
import { AppProvider } from '@toolpad/core/nextjs';
import { NextAppProvider } from '@toolpad/core/nextjs';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import { PageContainer } from '@toolpad/core/PageContainer';
import Head from 'next/head';
Expand Down Expand Up @@ -294,14 +294,14 @@ function AppLayout({ children }: { children: React.ReactNode }) {
<Head>
<meta name="viewport" content="initial-scale=1, width=device-width" />
</Head>
<AppProvider
<NextAppProvider
navigation={NAVIGATION}
branding={BRANDING}
session={session}
authentication={AUTHENTICATION}
>
{children}
</AppProvider>
</NextAppProvider>
</React.Fragment>
);
}
Expand Down
42 changes: 21 additions & 21 deletions docs/data/toolpad/core/integrations/react-router.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
title: React router - Integration
title: React Router - Integration
---

# React Router

<p class="description">To integrate Toolpad Core into a single-page app (with Vite, for example) using React Router, follow these steps.</p>

## Wrap all your pages in an `AppProvider`
## Wrap all your pages in a `ReactRouterAppProvider`

In your router configuration (e.g.: `src/main.tsx`), use a shared component or element (e.g.: `src/App.tsx`) as a root **layout route** that wraps the whole application with the `AppProvider` from `@toolpad/core/react-router-dom`.
In your router configuration (for example `src/main.tsx`), use a shared component or element (for example `src/App.tsx`) as a root **layout route** that wraps the whole application with the `ReactRouterAppProvider` from `@toolpad/core/react-router`.

You must use the `<Outlet />` component from `react-router-dom` in this root layout element or component.
You must use the `<Outlet />` component from `react-router` in this root layout element or component.

```tsx title="src/main.tsx"
import * as React from 'react';
import * as ReactDOM from 'react-dom/client';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { createBrowserRouter, RouterProvider } from 'react-router';
import App from './App';
import DashboardPage from './pages';
import OrdersPage from './pages/orders';
Expand All @@ -37,8 +37,8 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
import * as React from 'react';
import DashboardIcon from '@mui/icons-material/Dashboard';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
import { AppProvider } from '@toolpad/core/react-router-dom';
import { Outlet } from 'react-router-dom';
import { ReactRouterAppProvider } from '@toolpad/core/react-router';
import { Outlet } from 'react-router';
import type { Navigation } from '@toolpad/core';

const NAVIGATION: Navigation = [
Expand All @@ -63,20 +63,20 @@ const BRANDING = {

export default function App() {
return (
<AppProvider navigation={NAVIGATION} branding={BRANDING}>
<ReactRouterAppProvider navigation={NAVIGATION} branding={BRANDING}>
<Outlet />
</AppProvider>
</ReactRouterAppProvider>
);
}
```

## Create a dashboard layout

Create a layout file for your dashboard pages (e.g.: `src/layouts/dashboard.tsx`), to also be used as a layout route with the `<Outlet />` component from `react-router-dom`:
Create a layout file for your dashboard pages (for example `src/layouts/dashboard.tsx`), to also be used as a layout route with the `<Outlet />` component from `react-router`:

```tsx title="src/layouts/dashboard.tsx"
import * as React from 'react';
import { Outlet } from 'react-router-dom';
import { Outlet } from 'react-router';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import { PageContainer } from '@toolpad/core/PageContainer';

Expand All @@ -93,7 +93,7 @@ export default function Layout() {

The [`DashboardLayout`](/toolpad/core/react-dashboard-layout/) component provides a consistent layout for your dashboard pages, including a sidebar, navigation, and header. The [`PageContainer`](/toolpad/core/react-page-container/) component is used to wrap the page content, and provides breadcrumbs for navigation.

You can then add this layout component to your React Router configuration (e.g.: `src/main.tsx`), as a child of the root layout route created above.
You can then add this layout component to your React Router configuration (for example `src/main.tsx`), as a child of the root layout route created above.

```tsx title="src/main.tsx"
import Layout from './layouts/dashboard';
Expand All @@ -115,7 +115,7 @@ const router = createBrowserRouter([

## Create pages

Create a dashboard page (e.g.: `src/pages/index.tsx`) and an orders page (`src/pages/orders.tsx`).
Create a dashboard page (for example `src/pages/index.tsx`) and an orders page (`src/pages/orders.tsx`).

```tsx title="src/pages/index.tsx"
import * as React from 'react';
Expand All @@ -135,7 +135,7 @@ export default function OrdersPage() {
}
```

You can then add these page components as routes to your React Router configuration (e.g.: `src/main.tsx`). By adding them as children of the layout route created above, they are automatically wrapped with that dashboard layout:
You can then add these page components as routes to your React Router configuration (for example `src/main.tsx`). By adding them as children of the layout route created above, they are automatically wrapped with that dashboard layout:

```tsx title="src/main.tsx"
import DashboardPage from './pages';
Expand Down Expand Up @@ -205,8 +205,8 @@ export function useSession() {
import * as React from 'react';
import DashboardIcon from '@mui/icons-material/Dashboard';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
import { AppProvider } from '@toolpad/core/react-router-dom';
import { Outlet, useNavigate } from 'react-router-dom';
import { ReactRouterAppProvider } from '@toolpad/core/react-router';
import { Outlet, useNavigate } from 'react-router';
import type { Navigation, Session } from '@toolpad/core';
import { SessionContext } from './SessionContext';

Expand Down Expand Up @@ -250,14 +250,14 @@ export default function App() {

return (
<SessionContext.Provider value={sessionContextValue}>
<AppProvider
<ReactRouterAppProvider
navigation={NAVIGATION}
branding={BRANDING}
session={session}
authentication={{ signIn, signOut }}
>
<Outlet />
</AppProvider>
</ReactRouterAppProvider>
</SessionContext.Provider>
);
}
Expand All @@ -267,7 +267,7 @@ export default function App() {

```tsx title="src/layouts/dashboard.tsx"
import * as React from 'react';
import { Outlet, Navigate, useLocation } from 'react-router-dom';
import { Outlet, Navigate, useLocation } from 'react-router';
import { DashboardLayout } from '@toolpad/core/DashboardLayout';
import { PageContainer } from '@toolpad/core/PageContainer';
import { useSession } from '../SessionContext';
Expand Down Expand Up @@ -302,7 +302,7 @@ You can protect any page or groups of pages through this mechanism.
import * as React from 'react';
import { SignInPage } from '@toolpad/core/SignInPage';
import type { Session } from '@toolpad/core/AppProvider';
import { useNavigate } from 'react-router-dom';
import { useNavigate } from 'react-router';
import { useSession } from '../SessionContext';

const fakeAsyncGetSession = async (formData: any): Promise<Session> => {
Expand Down Expand Up @@ -354,7 +354,7 @@ export default function SignIn() {
```tsx title="src/main.tsx"
import * as React from 'react';
import * as ReactDOM from 'react-dom/client';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { createBrowserRouter, RouterProvider } from 'react-router';
import App from './App';
import Layout from './layouts/dashboard';
import DashboardPage from './pages';
Expand Down
4 changes: 2 additions & 2 deletions docs/data/toolpad/core/introduction/base-concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ You can pass the router implementation to the `AppProvider` component using the
:::

:::success
If you are using Next.js, use the `AppProvider` exported from `@toolpad/core/nextjs`.
If you are using Next.js, use the `NextAppProvider` exported from `@toolpad/core/nextjs`.

If you are building a single-page application (with [Vite](https://vite.dev/), for example) using React Router for routing, use the `AppProvider` exported from `@toolpad/core/react-router-dom`.
If you are building a single-page application (with [Vite](https://vite.dev/), for example) using React Router for routing, use the `ReactRouterAppProvider` exported from `@toolpad/core/react-router`.

This automatically sets up the router for you, so that you don't need to pass the `router` prop.
:::
Expand Down
2 changes: 1 addition & 1 deletion docs/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@
"react-dom": "18.3.1",
"react-hook-form": "7.53.2",
"react-is": "18.3.1",
"react-router": "6.26.2",
"react-router": "7.1.0",
"react-router-dom": "6.26.2",
"react-runner": "1.0.5",
"react-simple-code-editor": "0.14.1",
Expand Down
Loading

0 comments on commit 47e55ed

Please sign in to comment.