216 lines
4.8 KiB
Markdown
216 lines
4.8 KiB
Markdown
# Getting Started Reference
|
|
|
|
## Vite Template (Recommended)
|
|
|
|
The fastest way to start — official template includes everything:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
npm create vite@latest my-app -- --template react-ts
|
|
cd my-app
|
|
```
|
|
|
|
### 2. Install Packages
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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',
|
|
},
|
|
},
|
|
},
|
|
};
|
|
```
|
|
|
|
### 4. Import Styles
|
|
|
|
In your entry file (e.g., `src/main.tsx` or `src/App.tsx`):
|
|
|
|
```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
|
|
|
|
```tsx
|
|
// 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`:
|
|
|
|
```json
|
|
{
|
|
"cssVariables.lookupFiles": [
|
|
"**/*.css",
|
|
"node_modules/@mantine/core/styles.css"
|
|
]
|
|
}
|
|
```
|
|
|
|
## TypeScript Configuration
|
|
|
|
Mantine is fully typed. Your `tsconfig.json` should have:
|
|
|
|
```json
|
|
{
|
|
"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>`:
|
|
```tsx
|
|
import { ColorSchemeScript } from '@mantine/core';
|
|
|
|
// In your HTML head
|
|
<ColorSchemeScript defaultColorScheme="auto" />
|
|
```
|
|
|
|
### Hydration Warning
|
|
Spread `mantineHtmlProps` on `<html>` element:
|
|
```tsx
|
|
import { mantineHtmlProps } from '@mantine/core';
|
|
|
|
<html {...mantineHtmlProps}>
|
|
```
|