Getting started

Getting started (시작하기)

Mantine을 새 프로젝트에 도입하는 가장 쉬운 방법과, 프레임워크 없이 직접 설정하는 방법을 안내해 드릴게요. 템플릿 사용법부터 PostCSS・VS Code 설정, 학습 가이드까지 순서대로 설명해요.

출처: 문서

본문

템플릿으로 시작하기

가장 쉬운 시작 방법은 템플릿 중 하나를 사용하는 것이에요. 모든 템플릿에는 필요한 의존성과 사전 구성 설정이 포함되어 있어요. 일부 템플릿에는 Jest, Storybook, oxlint 같은 추가 기능도 포함돼요.

템플릿에는 @mantine/core와 @mantine/hooks 패키지만 포함되어 있어요. 추가 @mantine/* 패키지가 필요하면 해당 패키지의 설치 안내를 따라주세요.

템플릿으로 시작하려면 GitHub에서 템플릿을 열고 "Use this template" 버튼을 클릭해요. 이 기능을 사용하려면 GitHub 계정에 로그인해야 해요. GitHub에 익숙하지 않다면 이 문서에서 템플릿으로 프로젝트를 부트스트랩하는 방법을 자세히 볼 수 있어요.

공식 템플릿 목록:

next-app-template — Next.js app router + 전체 설정 (Jest, Storybook, oxlint) — Use template
next-pages-template — Next.js pages router + 전체 설정 (Jest, Storybook, oxlint) — Use template
next-app-min-template — Next.js app router + 최소 설정 (추가 도구 없음) — Use template
next-pages-min-template — Next.js pages router + 최소 설정 — Use template
next-vanilla-extract-template — Next.js + Vanilla Extract 예제 — Use template
vite-template — Vite + 전체 설정 (Vitest, oxfmt, Storybook, oxlint) — Use template
vite-min-template — Vite + 최소 설정 — Use template
vite-vanilla-extract-template — Vite + Vanilla Extract 예제 — Use template
gatsby-template — Gatsby + 기본 설정 — Use template
redwood-template — RedwoodJS + 기본 설정 — Use template

커뮤니티 템플릿

커뮤니티 템플릿은 커뮤니티 멤버가 만들고 관리해요. 여기에는 추가 기능과 서드파티 통합이 포함돼 있어요. 이 가이드에 따라 나만의 템플릿을 커뮤니티와 공유할 수 있어요:

t3-template — Next.js app router T3 stack — Use template
next-tailwind-template — Next.js app router + Mantine + Tailwind — Use template
next-bun-template — Next.js app router + Mantine + Bun — Use template
ship-template — Next.js, auth, MongoDB, Turborepo 기반 풀스택 보일러플레이트 — Use template
next-turborepo-template — App router + Mantine + Turborepo — Use template
nextra-documentation-template — Nextra + Mantine — Use template
fumadocs-documentation-template — Fumadocs + Mantine — Use template
next-saas-template — Mantine 기반 Next.js SaaS 보일러플레이트 — Use template
shaadkit-template — Next.js + Mantine + next-intl + Storybook + Vitest + Playwright — Use template
nx-vite-monorepo-template — Vite, GraphQL/Apollo, TypeScript, Storybook/CSS Modules 기반 NX 모노레포 — Use template
dashboard-template — Vite + Redux + i18next + auth + Mantine 대시보드 — Use template
supabase-template — Vite + Supabase + Mantine — Use template
waku-template — Vite + Waku + Mantine — Use template
tanstack-start-cloudflare-template — Tanstack Start + Cloudflare + Mantine — Use template
bun-vite-template — Bun + Vite + Mantine — Use template
electron-vite-template — Electron + Vite + React 데스크톱 앱 — Use template
react-router-template — 기본 react-router + Mantine — Use template

프레임워크 가이드

기존 프로젝트에 Mantine을 추가하거나 모든 것을 직접 설정하고 싶다면 아래 가이드 중 하나를 따라 Mantine과 선호하는 프레임워크로 시작하세요.

Vite — 권장. 단일 페이지 애플리케이션(SPA)에 가장 적합
Next.js — 권장. SSR이 있는 애플리케이션에 가장 적합
React Router — React Router 시작하기
Redwood — RedwoodJS 시작하기
Gatsby — Gatsby 시작하기

create-react-app과 함께 쓸 수 있나요?

Create React App은 2023년 초에 더 이상 사용되지 않았어요(관리자 코멘트). 새 프로젝트에는 권장하지 않아요. 대신 Vite 또는 Next.js를 권장해요. 버전 7.0부터 일부 Mantine 스타일링 기능은 Create React App에서 더 이상 공식 지원되지 않아요. 그래도 Create React App을 쓰고 싶다면 이 가이드를 따라주세요.

프레임워크 없이 시작하기

애플리케이션에서 사용할 패키지를 선택하세요:

패키지	설명
`@mantine/hooks`	상태 및 UI 관리를 위한 훅
`@mantine/core`	핵심 컴포넌트 라이브러리: 입력, 버튼, 오버레이 등
`@mantine/form`	폼 관리 라이브러리
`@mantine/dates`	날짜 입력, 캘린더
`@mantine/charts`	Recharts 기반 차트 라이브러리
`@mantine/notifications`	알림 시스템
`@mantine/code-highlight`	테마 색상과 스타일을 적용한 코드 하이라이트
`@mantine/tiptap`	Tiptap 기반 리치 텍스트 에디터
`@mantine/dropzone`	드래그 앤 드롭으로 파일 받기
`@mantine/carousel`	Embla 기반 캐러셀 컴포넌트
`@mantine/lightbox`	캐러셀 내비게이션이 있는 전체 화면 미디어 라이트박스
`@mantine/spotlight`	오버레이 커맨드 센터
`@mantine/modals`	중앙화된 모달 관리자
`@mantine/nprogress`	내비게이션 진행률

의존성을 설치해요:

yarn add @mantine/core @mantine/hooks

PostCSS 플러그인과 postcss-preset-mantine을 설치해요:

yarn add --dev postcss postcss-preset-mantine postcss-simple-vars

프레임워크 없는 PostCSS: 공식 지원되지 않는 프레임워크를 사용한다면 PostCSS를 수동으로 설정해야 할 수도 있어요. 프레임워크 문서에서 구체적인 안내를 참조하세요. 예를 들어 Webpack을 쓴다면 postcss-loader를 설치하고 설정해야 해요.

애플리케이션 루트에 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',
      },
    },
  },
};

애플리케이션 루트에 스타일 import를 추가해요. 보통 스타일은 루트 파일에 한 번만 import해요. 예를 들어 pages router를 쓰는 Next.js라면 _app.tsx 파일에서 import할 수 있어요:

// core styles are required for all packages
import '@mantine/core/styles.css';

// other css files are required only if
// you are using components from the corresponding package
// import '@mantine/dates/styles.css';
// import '@mantine/dropzone/styles.css';
// import '@mantine/code-highlight/styles.css';
// ...

애플리케이션을 MantineProvider로 감싸요:

import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  /** Put your mantine theme override here */
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      {/* Your app here */}
    </MantineProvider>
  );
}

애플리케이션에 서버 사이드 렌더링이 있다면 <head>에 ColorSchemeScript를 추가하고, <html> 요소에 mantineHtmlProps를 스프레드해 hydration 경고를 피하세요:

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

function Demo() {
  return (
    <html lang="en" {...mantineHtmlProps}>
      <head>
        <meta charSet="UTF-8" />
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1.0"
        />
        <title>My awesome app</title>

        <ColorSchemeScript />
      </head>
      <body>{/* Your app here */}</body>
    </html>
  );
}

이제 모든 준비가 끝났어요. 애플리케이션에서 Mantine 컴포넌트를 사용할 수 있어요.

VS Code 설정

기본적으로 VS Code는 postcss 문법을 인식하지 못해요. PostCSS Intellisense and Highlighting을 설치해 구문 하이라이팅을 활성화하고 $variable 오류를 없애야 해요.

CSS 변수 자동완성을 얻으려면 CSS Variable Autocomplete 확장을 설치해요. 그런 다음 프로젝트 루트 폴더에 .vscode/settings.json 파일을 만들고 다음 내용을 넣어요:

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

학습하기

코드를 작성하기 전에 Mantine의 테마링과 스타일링 옵션을 더 알아보는 것을 권장해요. 가장 중요한 문서 페이지는 다음과 같아요:

테마 객체 — 사용 가능한 테마 속성 알아보기
색상 — 테마 객체에 색상을 추가/교체하는 방법
CSS 모듈 — Mantine에서 CSS 모듈 사용법
postcss-preset-mantine — postcss-preset-mantine 함수와 믹스인 알아보기
반응형 스타일 — 컴포넌트에 반응형 스타일 적용하기
Styles API — 어떤 컴포넌트의 내부 요소도 스타일링하는 방법
다형성 컴포넌트 — 렌더링 요소를 바꾸기 위한 다형성 컴포넌트 사용법

Mantine 지원하기

프로젝트에 대한 모든 기여는 환영하고 감사해요. OpenCollective에서 프로젝트를 후원해 재정적으로 기여할 수 있어요. 후원은 프로젝트 유지와 새 기능 개발을 돕는답니다.

프로젝트를 지원하는 다른 방법:

GitHub Discussions에서 피드백 공유 — 대부분의 새 기능과 컴포넌트는 커뮤니티 피드백을 바탕으로 만들어져요.
Discord 및/또는 GitHub Discussions에서 다른 사람을 돕기. 매일 10~20개의 새 질문이 올라와요. 남을 도우면서 스스로도 배우게 돼요.
코드 리뷰 제공. @mantine/* 패키지의 소스 코드를 탐색하고 개선 의견을 주세요.
좋은 말 전하기. 보통 버그 리포트와 기능 요청만 받는데, 사람들이 Mantine을 즐겨 쓴다는 소식을 듣는 건 언제나 기뻐요.
GitHub에서 프로젝트에 별표(star) 달기. 프로젝트 성장에 도움이 되는 작은 일이에요.
Mantine 코드베이스에 기여. React/TypeScript 경험이 적다면 문서 개선을 도울 수 있고, 경험이 많다면 열린 이슈를 도와줘요.
직장에서 Mantine을 쓰고 회사가 프로젝트를 지원하려 한다면, 엔지니어 시간 중 일부를 Mantine 기여에 할애할 수 있어요.

Mantine for Figma

디자인은 개발 프로세스의 일부가 아니에요. 공식 Figma나 Sketch 디자인 파일은 없어요. 다만 Mantine 기반 Figma 컴포넌트를 제공하는 커뮤니티 주도 프로젝트가 있어요. 이 프로젝트는 Mantine 팀이 유지하지 않으며 최신 Mantine 버전과 동기화된다는 보장은 없어요.

Ravn의 디자인 파일
In The Zone의 디자인 파일
Devias의 디자인 파일
AlleyCorp Nord의 디자인 파일

라이선스

모든 @mantine/* 패키지는 MIT 라이선스로 배포돼요. 상업적이든 아니든 어떤 프로젝트에서든, 저작자 표시 여부와 관계없이 사용할 수 있어요. 모든 @mantine/* 패키지의 의존성도 MIT 라이선스로 배포돼요.

더 알아보기 (Learn more)

Vite 가이드 — SPA에 적합한 Vite 설정
Next.js 가이드 — SSR 애플리케이션을 위한 Next.js 설정