Customise SSR - How to integrate Mantine Component library

[zac-az]

I have setup Docusauras, but I would like to integrate it with Mantine so I can use my standardised components and colour scheme.

I have been unable to get Mantine to work correctly, due to SSR. The MantineProvider (which I have wrapped the docusauras app inside the Root theme component) breaks due to the server side render from docusauras (I presume a rendering mismatch).

Mantine does have this documentation on SSR: https://mantine.dev/guides/ssr/

I can't see how to integrate the two from the docusauras documentation.

Is there some way to customise the SSR logic so that I can ensure Mantine's styles are rendered on the server?

Or did anyone successfully integrate Mantine and Docusauras already?

Thanks in advance!

[slorber]

@zac-az Indeed we don't have a good way for you to wire the createStylesServer thing from Mantine, that's part of the issue #3236

Similarly, we don't support Material UI and other similar frameworks based on runtime CSS-in-JS, and you'll find various issues related to MUI in particular in this repo.

---

In general, I'd advise you not to use any runtime CSS-in-JS lib in Docusaurus, or at least if you want to do so, SSR won't work.

The industry trend is also to progressively abandon this kind of lib in favor of no-runtime CSS-in-JS libs.

Note that collecting critical stylesheets during SSR to inline them in the final html is not really supported by React Server Components atm, and we do plan to use Server Components in Docusaurus.

It doesn't mean it will break, but it will become more complicated and usage will be limited and also limiting the benefits of adopting React Server Components.

For example it's not possible to use any MUI or Mantine component in a React Server Component, they all should be client components (see mui/material-ui#35993 + mantinedev/mantine#2815)

Some libs like Chakra UI previously based on runtime are migrating to a no-runtime solution:: https://www.adebayosegun.com/blog/the-future-of-chakra-ui

---

So my advise is: don't use Mantine in Docusaurus, and prefer a zero-runtime CSS solution.

Even if you are able to make it work today, this could break in the future once we adopt React Server Components

If you really want to use it, opt-out of SSR by using <BrowserOnly> (https://docusaurus.io/docs/advanced/ssg#browseronly)

[zac-az]

Hi @slorber this is seriously helpful!

I totally agree with you on all fronts, and I usually go with a native css/scss in projects. Mantine itself has awesome components and is really easy to setup a project quickly, but was creating the dependency with css-in-js styles.

I found the links you gave very helpful, and it looks like Mantine will be migrating all their styles to native css, which is the first step towards this integration working. In the meantime, I will stick to Docusauras without Mantine.

I really appreciate your comprehensive answer!