First of all, thank you for showing interest in contributing to Mantine, all your contributions are extremely valuable to the project.

Ways to contribute

  • Improve Mantine docs – fix incomplete or missing docs, bad wording, examples or explanations
  • Give feedback – we are always open to critique and feedback, open a new discussion on Github and tell us everything
  • Build an open source application with Mantine – we will share it on examples page and our twitter
  • Build new feature or fix a bug – find an issue with help wanted label and create a pull request, or propose new component/hook and build it
  • Participate in accessibility testing – our goal is to provide the best UX for everybody, if you have experience in accessibility testing check Mantine components with your favorite tools and report an issue if something is not right
  • Share Mantine – share link to Mantine docs with everyone who can be interested

Setup project locally

This guide will help you setup project on your machine and explain how Mantine is built.

To start Mantine on your machine:

  • Fork mantine on Github and clone the repository
  • Run nvm use to set node version (see nvm repository for installation instructions)
  • Install dependencies with yarn (postinstall script will also install docs dependencies)
  • Run npm run storybook to start storybook and npm run docs to start documentation

If you experience any issues during setup, please, open an issue.

Commit convention

As this project is a monorepo it is important to write correct commit messages to keep git history clean. All commits made in this repository are divided in 3 groups:

  • package commits related to particular package
  • docs commits related to documentation
  • core commits only related to repository tooling and not associated with any package

Commit message consists of 3 parts:

[area] Optional title: Message


  • [core] Fix documentation deployment script – Change made in repository script, it is not related to documentation or any package
  • [docs] Update report issues link – Change related to documentation website
  • [@mantine/core] Button: Add theme focus styles – Change in @mantine/core package at Button component
  • [@mantine/hooks] use-list-state: Add remove handler – Change in @mantine/hooks package at use-list-state hook

How to open pull request

Please keep pull requests small and focused on specific issue.

  • Open an issue and describe the problem you will solve
  • Setup project locally
  • Create new branch out of master branch with name that best describes your changes
  • Make changes and commit them following commit convention
  • If you create new feature or fix a bug, please, include tests where possible
  • Run tests with npm test script and make sure they are passing
  • Create pull request

Mantine architecture

This part is dedicated to mantine architecture, read it to get better understanding of how Mantine is built, deployed and released.

Dependencies management

Mantine is a monorepo, it contains all packages and docs in single repository. Dependencies are managed with yarn v1 workspaces.

To manage dependencies more easily all of them are first added to main package.json and only then added to individual packages based on needs. For the same reason packages do not have any dev dependencies, all these dependencies are listed in main package.json.

To assure that all dependencies are in sync syncpack is used as part of testing script.

Shared tooling

Mantine monorepo has shared tooling configuration for all packages. It includes

  • Webpack config generator
  • Jest configuration
  • TypeScript configuration
  • ESLint and prettier configurations
  • Storybook
  • Syncpack
  • .gitignore

Since all tooling is managed on larger scale, individual package always includes only readme, package.json, _tsconfig.json and src folder. This approach keeps project simple and prevents duplication of dependencies and large chunks of configuration code.

Packages resolution

Mantine packages are located in src folder. Packages are divided in two groups: public and private. Public packages (e.g, @mantine/hooks, @mantine/core) are published to npm, private packages (e.g., @mantine/tests) are used as utilities for public packages or docs.

All packages are resolved with TypeScript paths in tsconfig and can be imported with regular syntax import { Button } from '@mantine/core'; from anywhere in project, including tests, docs and other packages.

npm scripts

All npm scripts are located at main package.json, individual packages do not have dedicated scripts.

Development scripts

  • storybook – starts storybook development server
  • docs – starts docs development server

Testing scripts

  • syncpack – runs syncpack
  • typecheck – runs TypeScript typechecking with tsc --noEmit on all packages and docs
  • lint – runs ESLint on src folder
  • jest – runs tests with jest
  • test – runs all above testing scripts

Docs scripts

  • docs:docgen – generates components types information with docgen script
  • docs:sizes – generates bundle size information for all packages
  • docs:clean – runs gatsby clean
  • docs:build – runs all above docs scripts and build production docs bundle
  • docs:deploy – runs all above docs scripts and deploys docs to Github Pages

Release scripts

  • build – builds given package, for example, npm run build @mantine/core to build single package or npm run build all to build all public packages
  • clean – removes dist folder from all packages
  • release:patch – releases 1.1.x patch version to npm
  • release:minor – releases 1.x.0 minor version to npm
  • release:major – releases x.0.0 major version to npm