mantine-kit

A Mantine 9 + React 19 + Vite 8 template, built and run with Bun. It is not just a starter with Mantine installed: src/ui/* is a wrapper kit around Mantine (imported everywhere via the @ui/* alias) that layers in a consistent design-system theme, a handful of shadowed/extended components (Table, TextInput, modals, notifications, forms), a lucide-backed icon registry, and boot-time safety nets. An ESLint import wall is the enforcement mechanism: it makes the kit the only door into Mantine, not just the recommended one. See AGENTS.md for the full contract.

The import wall

App code (src/app/**, src/main.tsx) cannot import @mantine/* packages, lucide-react, react-icons, or codemirror directly. eslint.config.js configures ESLint's core no-restricted-imports rule with a paths map from each Mantine package to the @ui/* barrel that replaces it (@mantine/core -> @ui/core, @mantine/hooks -> @ui/hooks, @mantine/form -> @ui/forms, and so on), each entry carrying its own error message:

Import from '@ui/core' instead. The kit barrel adds fixed defaults and overrides.

Write import { Button } from '@mantine/core' anywhere under src/app and bun run lint fails with that message pointing straight at the fix, instead of a generic "don't do that." src/ui/** is exempt from the outbound wall (it is the thing the wall protects), but a second, narrower rule applies even inside the kit: Table, TextInput, and CopyButton from @mantine/core are blocked there too, in favor of the shadowed versions in @ui/core. See AGENTS.md, section 1, for the full rule set.

Quickstart

Scaffold a new app from this template with the bundled create CLI, run from a checkout of this repo:

bun create-cli/create.ts my-app
cd my-app
bun install
bun run dev

This copies the template, renames it to my-app everywhere the template's own working name appears, and initializes a fresh git repo with one commit. The package is pre-publish (create-mantine-kit is not yet live on npm); once it is, per PUBLISHING.md, the same scaffold becomes bunx create-mantine-kit my-app, no checkout needed. See create-cli/README.md for the full behavior.

To work in this repo directly instead (e.g. to extend the kit itself):

bun install
bun run dev

Scripts

Script	What it does
bun run dev	Start the Vite dev server.
bun run test	Run the test suite (Vitest). Add -- --run for a single non-watch run.
bun run lint	ESLint over src and create-cli.
bun run typecheck	tsc -b project-references typecheck, no emit.
bun run build	Typecheck (tsc -b) then production build (vite build).
bun run build-storybook	Build the static Storybook site.
bun run storybook	Run Storybook locally in dev mode (port 6006).
bun run format	Format the repo with Prettier (--write).
bun run format:check	Check formatting without writing (what CI runs).
bun run debrand	Guard against leftover source-project naming (scripts/debrand-check.sh).
bun run preview	Preview the production build locally.

Storybook

Every generic component under src/ui/core/** (and the design-system, forms, icons, and notifications modules) ships a .stories.tsx file alongside it. Run bun run storybook for the live dev server, or bun run build-storybook to produce the static site in storybook-static/.

Demo site

src/app is a small multi-page site (routed by a deliberately disposable hand-rolled router in src/app/router/ -- the kit itself is router-agnostic, see AGENTS.md §10): a landing page, a /docs section with per-topic guides (theming, hooks, modals, notifications, forms, app chrome, import walls, scaffolding) plus a per-component reference -- one page per documented kit component, each with a live demo, usage snippet, and props table -- and /demo, the full-screen compound PageShell showcase running inside the kit's own mini-icon-rail chrome (RailShell + PageShell). Run bun run dev and open it to see the kit's components wired up in context.

Learn more

• AGENTS.md -- the agent/contributor contract: import walls, adding components, the icon registry, theme overrides, facade usage (modals/notifications/forms), storage and color-scheme hooks, the boot family, and scaffolding.
• create-cli/README.md -- full detail on what the scaffold CLI does and how to maintain it.