# NextJs
# Usage with Next.js
## Generate new application
Follow the [create-next-app](https://nextjs.org/docs/pages/api-reference/create-next-app) guide to
create a new Next.js application:
## Installation
## PostCSS setup
Install PostCSS plugins and [postcss-preset-mantine](https://mantine.dev/llms/styles-postcss-preset.md):
```bash
yarn add postcss postcss-preset-mantine postcss-simple-vars
```
```bash
npm install postcss postcss-preset-mantine postcss-simple-vars
```
Create a `postcss.config.cjs` file at the root of your application with the following content:
```js
module.exports = {
plugins: {
'postcss-preset-mantine': {},
'postcss-simple-vars': {
variables: {
'mantine-breakpoint-xs': '36em',
'mantine-breakpoint-sm': '48em',
'mantine-breakpoint-md': '62em',
'mantine-breakpoint-lg': '75em',
'mantine-breakpoint-xl': '88em',
},
},
},
};
```
## Setup with pages router
Add styles imports and [MantineProvider](https://mantine.dev/llms/theming-mantine-provider.md) to the `pages/_app.tsx` file:
```tsx
// Import styles of packages that you've installed.
// All packages except `@mantine/hooks` require styles imports
import '@mantine/core/styles.css';
import type { AppProps } from 'next/app';
import { createTheme, MantineProvider } from '@mantine/core';
const theme = createTheme({
/** Put your mantine theme override here */
});
export default function App({ Component, pageProps }: AppProps) {
return (
);
}
```
Create a `pages/_document.tsx` file with the [ColorSchemeScript](https://mantine.dev/llms/theming-color-schemes.md) component.
Note that it's required even if you use only one color scheme in your application.
```tsx
import { Head, Html, Main, NextScript } from 'next/document';
import { ColorSchemeScript, mantineHtmlProps } from '@mantine/core';
export default function Document() {
return (
);
}
```
All set! Start the development server:
```bash
npm run dev
```
## Setup with app router
Add [MantineProvider](https://mantine.dev/llms/theming-mantine-provider.md), [ColorSchemeScript](https://mantine.dev/llms/theming-color-schemes.md)
and styles imports to the `app/layout.tsx` file:
```tsx
// Import styles of packages that you've installed.
// All packages except `@mantine/hooks` require styles imports
import '@mantine/core/styles.css';
import { ColorSchemeScript, MantineProvider, mantineHtmlProps } from '@mantine/core';
export const metadata = {
title: 'My Mantine app',
description: 'I have followed setup instructions carefully',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
All set! Start the development server:
```bash
npm run dev
```
## app + pages router together
If you use both app and pages router in one application, you need to setup both `pages/_app.tsx`
and `app/layout.tsx` files as described above.
## Next.js Link with polymorphic components
```tsx
import Link from 'next/link';
import { Button } from '@mantine/core';
function Demo() {
return (
);
}
```
## Server components
All Mantine components require context to support [default props](https://mantine.dev/llms/theming-default-props.md)
and [Styles API](https://mantine.dev/llms/styles-styles-api.md). Mantine components cannot be used as server components.
This means that components will render both on the server and client.
Entry points of all `@mantine/*` packages (`index.js` files) have the `'use client';` directive at the
top of the file – you don't need to add `'use client';` to your pages/layouts/components.
## Compound components in server components
Some components like [Popover](https://mantine.dev/llms/core-popover.md) have associated compound components (`Component.XXX`),
where `XXX` is a compound component name. Compound components cannot be used in server components.
Instead, use the `ComponentXXX` syntax or add the `'use client';` directive to the top of the file.
Example that won't work in server components:
```tsx
import { Popover } from '@mantine/core';
// This will throw an error
export default function Page() {
return (
TargetDropdown
);
}
```
Example with `'use client';` directive:
```tsx
'use client';
import { Popover } from '@mantine/core';
// No error
export default function Page() {
return (
TargetDropdown
);
}
```
Example with `ComponentXXX` syntax:
```tsx
import {
Popover,
PopoverDropdown,
PopoverTarget,
} from '@mantine/core';
// No error
export default function Page() {
return (
TriggerDropdown
);
}
```
## app router tree shaking
To enable tree shaking with app router, enable the experimental `optimizePackageImports` feature in
your `next.config.mjs`:
```tsx
export default {
// ...other configuration
experimental: {
optimizePackageImports: ['@mantine/core', '@mantine/hooks'],
},
};
```
## Troubleshooting
If you have any issues with Mantine in your Next.js application, please check the
[Help Center article](https://help.mantine.dev/q/server-components) that covers
the most common issues with app router and server components.