monitoring-app/.agents/skills/mantine-dev/references/getting-started.md

Getting Started Reference

Vite Template (Recommended)

The fastest way to start — official template includes everything:

# Clone template
git clone https://github.com/mantinedev/vite-template my-app
cd my-app

# Install dependencies
yarn install  # or npm install

# Start development
yarn dev

Template Features

• PostCSS with postcss-preset-mantine
• TypeScript configured
• Storybook setup
• Vitest with React Testing Library
• ESLint with eslint-config-mantine
• Prettier configured

Manual Setup

1. Create Vite Project

npm create vite@latest my-app -- --template react-ts
cd my-app

2. Install Packages

# Core (required)
npm install @mantine/core @mantine/hooks

# PostCSS (required for responsive styles)
npm install -D postcss postcss-preset-mantine postcss-simple-vars

# Optional packages
npm install @mantine/form          # Forms with validation
npm install @mantine/dates dayjs   # Date/time components
npm install @mantine/notifications # Toast notifications
npm install @mantine/modals        # Modal manager
npm install @mantine/charts recharts # Charts
npm install @mantine/dropzone      # File upload
npm install @mantine/spotlight     # Command palette (Cmd+K)
npm install @mantine/code-highlight # Code syntax highlighting
npm install @mantine/carousel embla-carousel-react # Carousel
npm install @mantine/tiptap @tiptap/react @tiptap/pm @tiptap/starter-kit # Rich text editor

3. Configure PostCSS

Create postcss.config.cjs:

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',
      },
    },
  },
};

4. Import Styles

In your entry file (e.g., src/main.tsx or src/App.tsx):

// Required - core styles
import '@mantine/core/styles.css';

// Package-specific styles (import only what you use)
import '@mantine/dates/styles.css';
import '@mantine/notifications/styles.css';
import '@mantine/code-highlight/styles.css';
import '@mantine/dropzone/styles.css';
import '@mantine/spotlight/styles.css';
import '@mantine/carousel/styles.css';
import '@mantine/tiptap/styles.css';
// Note: @mantine/form and @mantine/hooks have no styles

5. Setup MantineProvider

// src/App.tsx
import '@mantine/core/styles.css';

import { MantineProvider, createTheme } from '@mantine/core';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

const theme = createTheme({
  // Your theme customization
  primaryColor: 'blue',
  fontFamily: 'Inter, sans-serif',
});

function App() {
  return (
    <MantineProvider theme={theme}>
      <BrowserRouter>
        <Routes>
          {/* Your routes */}
        </Routes>
      </BrowserRouter>
    </MantineProvider>
  );
}

export default App;

Project Structure

Recommended structure for Mantine projects:

src/
├── components/
│   ├── Layout/
│   │   ├── AppShell.tsx
│   │   ├── Header.tsx
│   │   └── Navbar.tsx
│   └── ui/                # Custom UI components
├── pages/
│   ├── Home.tsx
│   └── Settings.tsx
├── hooks/                  # Custom hooks
├── theme/
│   ├── index.ts           # createTheme export
│   └── components.ts      # Component default props
├── utils/
├── App.tsx
├── main.tsx
└── App.module.css         # CSS modules

VS Code Setup

Install recommended extensions:

1. PostCSS Intellisense and Highlighting
   For postcss syntax support and $variable recognition.

2. CSS Variable Autocomplete
   For Mantine CSS variables autocomplete.

Create .vscode/settings.json:

{
  "cssVariables.lookupFiles": [
    "**/*.css",
    "node_modules/@mantine/core/styles.css"
  ]
}

TypeScript Configuration

Mantine is fully typed. Your tsconfig.json should have:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "react-jsx",
    "skipLibCheck": true
  }
}

Common Issues

Styles Not Loading

Ensure @mantine/core/styles.css is imported before any component usage.

PostCSS Mixins Not Working

Check that postcss-preset-mantine is installed and configured in postcss.config.cjs.

Dark Mode Flash

For SSR apps, add ColorSchemeScript to <head>:

import { ColorSchemeScript } from '@mantine/core';

// In your HTML head
<ColorSchemeScript defaultColorScheme="auto" />

Hydration Warning

Spread mantineHtmlProps on <html> element:

import { mantineHtmlProps } from '@mantine/core';

<html {...mantineHtmlProps}>