Skip to content

Commit a2d7cef

Browse files
lazarvlazarv
authored
docs: integrations update (#316)
Closes #44 Replaces the "Coming soon" placeholder pages under Integrations with full documentation: - **TanStack Query** — setup, server-side prefetching with `HydrationBoundary`, client hydration, isomorphic data fetching, nested hydration boundaries - **Mantine UI** — PostCSS configuration, `MantineProvider` setup, navigation with `component={Link}`, extension packages, `ClientOnly` usage - **Material UI** — Emotion/theme setup, `ThemeProvider` layout, navigation via `component` prop, ESM icon imports Also adds Japanese translations for all three pages.
1 parent 5e24d8f commit a2d7cef

7 files changed

Lines changed: 1232 additions & 7 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -551,7 +551,18 @@ jobs:
551551
- test-build-start-apps-edge
552552
- test-build-start-apps-edge-entry
553553
- test-rsc
554-
if: always()
554+
if: >-
555+
always() && !(
556+
needs.test-dev-base.result == 'skipped' &&
557+
needs.test-build-start-base.result == 'skipped' &&
558+
needs.test-build-start-base-edge.result == 'skipped' &&
559+
needs.test-build-start-base-edge-entry.result == 'skipped' &&
560+
needs.test-dev-apps.result == 'skipped' &&
561+
needs.test-build-start-apps.result == 'skipped' &&
562+
needs.test-build-start-apps-edge.result == 'skipped' &&
563+
needs.test-build-start-apps-edge-entry.result == 'skipped' &&
564+
needs.test-rsc.result == 'skipped'
565+
)
555566
runs-on: ubuntu-latest
556567
steps:
557568
- name: Checkout

‎docs/src/pages/en/(pages)/integrations/mantine.mdx‎

Lines changed: 188 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,198 @@
22
title: Mantine UI
33
category: Integrations
44
order: 5
5-
contents: false
65
---
76

87
import Link from "../../../../components/Link.jsx";
98

109
# Mantine UI
1110

12-
> Coming soon.
11+
`@lazarv/react-server` is compatible with [Mantine](https://mantine.dev/), a full-featured React component library. You can use Mantine components in your client components with server-side rendering support, PostCSS configuration for Mantine's styling system, and the `MantineProvider` for theming.
12+
13+
<Link name="installation">
14+
## Installation
15+
</Link>
16+
17+
Install Mantine and its required PostCSS dependencies:
18+
19+
```sh
20+
pnpm add @mantine/core @mantine/hooks
21+
pnpm add -D postcss postcss-preset-mantine postcss-simple-vars
22+
```
23+
24+
<Link name="postcss-configuration">
25+
## PostCSS configuration
26+
</Link>
27+
28+
Mantine requires a PostCSS configuration with the `postcss-preset-mantine` plugin and breakpoint variables:
29+
30+
```js filename="postcss.config.cjs"
31+
module.exports = {
32+
plugins: {
33+
"postcss-preset-mantine": {},
34+
"postcss-simple-vars": {
35+
variables: {
36+
"mantine-breakpoint-xs": "36em",
37+
"mantine-breakpoint-sm": "48em",
38+
"mantine-breakpoint-md": "62em",
39+
"mantine-breakpoint-lg": "75em",
40+
"mantine-breakpoint-xl": "88em",
41+
},
42+
},
43+
},
44+
};
45+
```
46+
47+
<Link name="provider-setup">
48+
## Provider setup
49+
</Link>
50+
51+
Import the core Mantine styles and wrap your app with `MantineProvider` in your root layout. Include the `ColorSchemeScript` in the `<head>` to prevent a flash of unstyled content:
52+
53+
```tsx filename="src/pages/layout.tsx"
54+
import "@mantine/core/styles.css";
55+
56+
import { ColorSchemeScript, createTheme, MantineProvider } from "@mantine/core";
57+
58+
const theme = createTheme({
59+
/** Put your mantine theme override here */
60+
});
61+
62+
export default function Layout({ children }: { children: React.ReactNode }) {
63+
return (
64+
<html lang="en" data-mantine-color-scheme="light" suppressHydrationWarning>
65+
<head>
66+
<ColorSchemeScript />
67+
</head>
68+
<body suppressHydrationWarning>
69+
<MantineProvider theme={theme}>
70+
{children}
71+
</MantineProvider>
72+
</body>
73+
</html>
74+
);
75+
}
76+
```
77+
78+
<Link name="using-components">
79+
## Using components
80+
</Link>
81+
82+
Mantine components that use React hooks or browser APIs must be used in client components. Create a client component and import the Mantine components you need:
83+
84+
```tsx filename="src/components/Counter.tsx"
85+
"use client";
86+
87+
import { useState } from "react";
88+
import { Button, Group, Text } from "@mantine/core";
89+
90+
export function Counter() {
91+
const [count, setCount] = useState(0);
92+
93+
return (
94+
<Group>
95+
<Button onClick={() => setCount((c) => c - 1)}>-</Button>
96+
<Text>{count}</Text>
97+
<Button onClick={() => setCount((c) => c + 1)}>+</Button>
98+
</Group>
99+
);
100+
}
101+
```
102+
103+
Then use the client component from your server component page:
104+
105+
```tsx filename="src/pages/index.tsx"
106+
import { Counter } from "../components/Counter";
107+
108+
export default function HomePage() {
109+
return <Counter />;
110+
}
111+
```
112+
113+
<Link name="navigation">
114+
## Navigation
115+
</Link>
116+
117+
To use Mantine's navigation components like `NavLink` with `@lazarv/react-server`'s client-side navigation, pass the framework's `Link` component via the `component` prop:
118+
119+
```tsx filename="src/components/MainNavigation.tsx"
120+
"use client";
121+
122+
import { NavLink } from "@mantine/core";
123+
import { Link, usePathname } from "@lazarv/react-server/navigation";
124+
125+
export function MainNavigation() {
126+
const pathname = usePathname();
127+
128+
return (
129+
<>
130+
<NavLink
131+
component={Link}
132+
to="/"
133+
label="Home"
134+
active={pathname === "/"}
135+
/>
136+
<NavLink
137+
component={Link}
138+
to="/about"
139+
label="About"
140+
active={pathname === "/about"}
141+
/>
142+
</>
143+
);
144+
}
145+
```
146+
147+
<Link name="extension-packages">
148+
## Extension packages
149+
</Link>
150+
151+
Mantine offers many extension packages for additional functionality. Import their styles in the pages or layouts where they are used:
152+
153+
```tsx filename="src/pages/dates.tsx"
154+
import "@mantine/dates/styles.css";
155+
156+
import { MyDates } from "../components/MyDates";
157+
158+
export default function DatesPage() {
159+
return <MyDates />;
160+
}
161+
```
162+
163+
Some commonly used Mantine extensions and their style imports:
164+
165+
| Package | Style import |
166+
|---------|-------------|
167+
| `@mantine/dates` | `@mantine/dates/styles.css` |
168+
| `@mantine/charts` | `@mantine/charts/styles.css` |
169+
| `@mantine/notifications` | `@mantine/notifications/styles.css` |
170+
| `@mantine/code-highlight` | `@mantine/code-highlight/styles.css` |
171+
| `@mantine/carousel` | `@mantine/carousel/styles.css` |
172+
| `@mantine/spotlight` | `@mantine/spotlight/styles.css` |
173+
| `@mantine/nprogress` | `@mantine/nprogress/styles.css` |
174+
| `@mantine/tiptap` | `@mantine/tiptap/styles.css` |
175+
| `@mantine/dropzone` | `@mantine/dropzone/styles.css` |
176+
177+
<Link name="client-only-components">
178+
## Client-only components
179+
</Link>
180+
181+
Some components (like charts that depend on browser APIs) cannot be server-side rendered. Use `ClientOnly` from `@lazarv/react-server/client` to render them only on the client:
182+
183+
```tsx filename="src/pages/charts.tsx"
184+
import "@mantine/charts/styles.css";
185+
186+
import { ClientOnly } from "@lazarv/react-server/client";
187+
import { MyAreaChart } from "../components/MyAreaChart";
188+
189+
export default function ChartsPage() {
190+
return (
191+
<ClientOnly>
192+
<MyAreaChart />
193+
</ClientOnly>
194+
);
195+
}
196+
```
197+
198+
> Check out the [Mantine example](https://github.com/lazarv/react-server/tree/main/examples/mantine) to see a complete example of using Mantine UI with `@lazarv/react-server`.
13199

‎docs/src/pages/en/(pages)/integrations/mui.mdx‎

Lines changed: 164 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,174 @@
22
title: Material UI
33
category: Integrations
44
order: 6
5-
contents: false
65
---
76

87
import Link from "../../../../components/Link.jsx";
98

109
# Material UI
1110

12-
> Coming soon.
11+
`@lazarv/react-server` is compatible with [Material UI (MUI)](https://mui.com/material-ui/), a popular React component library implementing Google's Material Design. MUI uses Emotion for CSS-in-JS styling, which works out of the box with `@lazarv/react-server`.
12+
13+
<Link name="installation">
14+
## Installation
15+
</Link>
16+
17+
Install Material UI and its required dependencies:
18+
19+
```sh
20+
pnpm add @mui/material @emotion/react @emotion/styled
21+
```
22+
23+
Optionally, install the Roboto font and Material Icons:
24+
25+
```sh
26+
pnpm add @fontsource/roboto @mui/icons-material
27+
```
28+
29+
<Link name="theme-setup">
30+
## Theme setup
31+
</Link>
32+
33+
Create a theme file to configure your Material UI theme:
34+
35+
```js filename="app/theme.mjs"
36+
import { createTheme } from "@mui/material/styles";
37+
38+
const theme = createTheme({
39+
palette: {
40+
mode: "light",
41+
},
42+
typography: {
43+
fontFamily: "Roboto",
44+
},
45+
});
46+
47+
export default theme;
48+
```
49+
50+
<Link name="provider-setup">
51+
## Provider setup
52+
</Link>
53+
54+
Material UI requires a `ThemeProvider` and `CssBaseline` for proper theming and baseline styles. Create a client component that wraps your app:
55+
56+
```jsx filename="app/components/Layout.jsx"
57+
"use client";
58+
59+
import Container from "@mui/material/Container";
60+
import CssBaseline from "@mui/material/CssBaseline";
61+
import { ThemeProvider } from "@mui/material/styles";
62+
63+
import theme from "../theme";
64+
65+
export default function Layout({ children }) {
66+
return (
67+
<ThemeProvider theme={theme}>
68+
<CssBaseline />
69+
<Container maxWidth="lg">
70+
{children}
71+
</Container>
72+
</ThemeProvider>
73+
);
74+
}
75+
```
76+
77+
Then set up your root layout to import the font and use the `Layout` provider component:
78+
79+
```jsx filename="app/layout.jsx"
80+
import "@fontsource/roboto/300.css";
81+
import "@fontsource/roboto/400.css";
82+
import "@fontsource/roboto/500.css";
83+
import "@fontsource/roboto/700.css";
84+
85+
import Layout from "./components/Layout";
86+
87+
export default function RootLayout({ children }) {
88+
return (
89+
<html lang="en" suppressHydrationWarning>
90+
<head>
91+
<meta charSet="UTF-8" />
92+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
93+
<title>My App</title>
94+
</head>
95+
<body suppressHydrationWarning>
96+
<Layout>{children}</Layout>
97+
</body>
98+
</html>
99+
);
100+
}
101+
```
102+
103+
<Link name="navigation">
104+
## Navigation
105+
</Link>
106+
107+
To use MUI link and button components with `@lazarv/react-server`'s client-side navigation, pass the framework's `Link` component via the `component` prop:
108+
109+
```jsx filename="app/page.jsx"
110+
"use client";
111+
112+
import { Link as ReactServerLink } from "@lazarv/react-server/navigation";
113+
import Link from "@mui/material/Link";
114+
115+
export default function Home() {
116+
return (
117+
<Link to="/about" color="secondary" component={ReactServerLink}>
118+
Go to the about page
119+
</Link>
120+
);
121+
}
122+
```
123+
124+
The same pattern works with MUI `Button` for navigation:
125+
126+
```jsx filename="app/about/page.jsx"
127+
"use client";
128+
129+
import { Link as ReactServerLink } from "@lazarv/react-server/navigation";
130+
import Button from "@mui/material/Button";
131+
132+
export default function About() {
133+
return (
134+
<Button to="/" component={ReactServerLink}>
135+
Go to the home page
136+
</Button>
137+
);
138+
}
139+
```
140+
141+
<Link name="server-components">
142+
## Server components
143+
</Link>
144+
145+
Some MUI components that don't rely on browser APIs or React hooks can be used directly in server components. Components like `Typography` and `Link` (without navigation) work in server components:
146+
147+
```jsx filename="app/components/Copyright.jsx"
148+
import Typography from "@mui/material/Typography";
149+
import Link from "@mui/material/Link";
150+
151+
export default function Copyright() {
152+
return (
153+
<Typography variant="body2" color="text.secondary" align="center">
154+
{"Copyright © "}
155+
<Link color="inherit" href="https://mui.com/">
156+
Your Website
157+
</Link>{" "}
158+
{new Date().getFullYear()}.
159+
</Typography>
160+
);
161+
}
162+
```
163+
164+
<Link name="icons">
165+
## Icons
166+
</Link>
167+
168+
When using `@mui/icons-material`, import icons from the ESM path for proper module resolution:
169+
170+
```jsx
171+
import LightbulbOutlined from "@mui/icons-material/esm/LightbulbOutlined";
172+
```
173+
174+
> Check out the [Material UI example](https://github.com/lazarv/react-server/tree/main/examples/mui) to see a complete example of using MUI with `@lazarv/react-server`.
13175

0 commit comments

Comments
 (0)