---
title: "Vite plugin"
description: "@maz-ui/vite-plugin brings icons by name (<MazIcon icon=\"x-mark\" />, only the icons of each page bundled), removes the unused CSS of maz-ui at build time and keeps only the theme presets your app loads."
package: "@maz-ui/vite-plugin"
url: "https://maz-ui.com/ecosystem/vite-plugin"
---

# Vite plugin

> @maz-ui/vite-plugin brings icons by name (<MazIcon icon="x-mark" />, only the icons of each page bundled), removes the unused CSS of maz-ui at build time and keeps only the theme presets your app loads.

- Package: `@maz-ui/vite-plugin`
- Import: `import { MazUi } from '@maz-ui/vite-plugin'`
- Web: https://maz-ui.com/ecosystem/vite-plugin

@maz-ui/vite-plugin brings icons by name (, only the icons of each page bundled), removes the unused CSS of maz-ui at build time and keeps only the theme presets your app loads.

`MazUi()` holds the plugins of maz-ui:

- **Icons by name**: `icon="x-mark"` without an import, with the SVG of your project and the types of the names.
- **CSS purge**: removes from the CSS of maz-ui what your app does not use.
- **Theme presets**: keeps in the build only the theme presets your app loads by name.

**Tip: Nuxt**

With `@maz-ui/nuxt`, you do not install anything: the module adds them, see [`icons`](https://maz-ui.com/ecosystem/nuxt.md#icons), [`css.purge`](https://maz-ui.com/ecosystem/nuxt.md#css-configuration) and [`theme.presets`](https://maz-ui.com/ecosystem/nuxt.md#theme-system).

## Installation

For Vue apps built with Vite (`vite >=6 <9`):

```bash [pnpm]
pnpm add -D @maz-ui/vite-plugin
```

```bash [npm]
npm install -D @maz-ui/vite-plugin
```

```bash [yarn]
yarn add -D @maz-ui/vite-plugin
```

It requires `maz-ui >= 5.7.0`. Keep both on the same version.

## Usage

```ts
// vite.config.ts
import { MazUi } from '@maz-ui/vite-plugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    MazUi(),
  ],
})
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `icons` | `boolean \| object` | `true` | Icons by name |
| `purge` | `boolean \| object` | `true` | CSS purge |
| `presets` | `string[]` | every preset | Theme presets |

## Icons by name

```vue
<template>
  <MazIcon icon="x-mark" />
  <MazIcon :icon="isDark ? 'moon' : 'sun'" />
  <MazBtn start-icon="arrow-right">
    Next
  </MazBtn>
  <MazSvg icon="flag-fr" width="32" />
  <MazSvg icon="hero" /> <!-- src/icons/hero.svg -->
</template>
```

Every icon of [@maz-ui/icons](https://maz-ui.com/ecosystem/icons/index.md) (`x-mark`, `logo-vue`, `flag-fr`) and every SVG of `src/icons` is available by name, in every prop that takes an icon (`icon`, `start-icon`, `end-icon`...).

- **Only the icons of each page are bundled**: the plugin finds the names a file uses and adds them to the chunk of this file. An icon of a single route is not in the entry chunk.
- **SSR**: the icon is in the HTML of the server.
- **Typed**: the plugin writes `src/maz-icons.d.ts`, for the autocompletion of the names.
- **No reload in dev** when a page uses a new icon.
- **Imports from the root**: `import { MazStar, LazyMazHome } from '@maz-ui/icons'` is rewritten to the module of each icon (`@maz-ui/icons/static/MazStar`), the dev server does not load the 860+ icons.

### Which names are found

The plugin reads the strings of the keys, variables and attributes whose name contains `icon`, and the strings with your `prefix`:

```ts
const items = [{ label: 'Home', icon: 'home' }] // found
const icon = computed(() => isDark.value ? 'moon' : 'sun') // found
h(MazIcon, { icon: 'bell' }) // found
const names = ['home', 'user'] // not found: no icon context
```

A name built at runtime (from an API, `` `flag-${code}` ``) is not found: add it to `safelist`. An unknown name renders the `fallback` of MazIcon, with a warning in the console.

### SVG of the project

`src/icons/hero.svg` is `hero`, `src/icons/brand/logo.svg` is `brand-logo`. They are optimized with the [default svgo config](https://maz-ui.com/ecosystem/vite-svg-loader.md#default-svgo-config). A file with the name of an icon of maz-ui replaces it, with a warning. Set a `prefix` to keep them apart:

```ts
MazUi({
  icons: { dir: 'src/assets/svg', prefix: 'app' },
})
```

```vue
<MazSvg icon="app:hero" />
```

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `string` | `'src/icons'` | Folder of the SVG of the project |
| `prefix` | `string` | | Prefix of their names: `app` gives `app:hero` |
| `safelist` | `string[]` | `[]` | Names the plugin can not find (built at runtime): registered wherever icons are used |
| `dts` | `string \| boolean` | `'src/maz-icons.d.ts'` | File of the types of the names, `false` to not write it |
| `strict` | `boolean` | `false` | `icon` only accepts the known names, URLs and raw SVG: a typo is a type error |
| `svgoConfig` | `Config \| (defaults) => Config` | | svgo config of the SVG of the project |

The types augment `maz-ui`: keep `src/maz-icons.d.ts` in the `include` of your `tsconfig.json` (it is under `src`). Commit it, like the `components.d.ts` of unplugin-vue-components: `vue-tsc` in the CI and a fresh clone have the names without running Vite (without the file, `icon` is a plain `string`). It only changes when you add an SVG or upgrade maz-ui.

**Details: Your own components with an icon prop**

Type the prop with `MazIconString` (a string, from `maz-ui`) or `MazIconValue` (a string or a component, from `maz-ui/components/MazIcon`), and make the component generic:

```vue
<script setup lang="ts" generic="_T">
import type { MazIconValue } from 'maz-ui/components/MazIcon'

defineProps<{ icon?: MazIconValue }>()
</script>
```

Passed as a `Component` (`h()`, a route), a component that is not generic fails with `TS2590: Expression produces a union type that is too complex to represent`: TypeScript compares its props with the 860+ names. The components of maz-ui with an icon prop are generic for this reason: type their template refs with [`GenericInstanceType`](https://maz-ui.com/ecosystem/utils/types/generic-instance-type.md), `InstanceType` does not work with a generic component.

## CSS purge

`maz-ui/style.css` holds the styles of every component. Most apps use a few of them: the plugin keeps the rules of what your code uses and removes the rest, in the CSS of your production build.

```ts
MazUi({
  purge: { safelist: ['text-title-1'] },
})

// or alone
import { MazUiPurgeCss } from '@maz-ui/vite-plugin'

MazUiPurgeCss()
```

Keep importing `maz-ui/style.css` as usual. The build prints a report:

```txt
[maz-ui:purge-css] 86.9 kB -> 32.8 kB of maz-ui CSS (-62%, 412 unused classes removed)
```

### How it works

1. At the build of maz-ui, `dist/css/purge-manifest.json` lists every class of `style.css`, the public utilities, and for each entry (`components/MazBtn`, `plugins/toast`, `directives/vTooltip`...) the classes it renders, with the entries it imports.
2. In your build, the plugin scans the source files of the project and finds the entries you use by their names: `MazBtn`, `<maz-btn>`, `LazyMazBtn`, `useToast`, `v-tooltip`, `ToastPlugin`... A namespace import of a barrel (`import * as components from 'maz-ui/components'`) keeps every component. It also finds the public utilities used (`text-title-1`, `padded-container`...).
3. When Vite transforms a CSS file, the plugin removes the rules of the unused entries and utilities, before the hash of the asset is computed, so the cache stays correct. It also removes the classes of `main.css` that no component renders.
4. At the end of the build, it checks the final JS and HTML: a purged class found there prints a warning, see Bundle check.

The plugin only touches the CSS of maz-ui. The CSS of your own app is never modified.

### Gains

Measured with `vite build`, the maz-ui preset, on the CSS assets of the app. Every Vue app imports `maz-ui/style.css`.

| App | Without purge | With purge | Saved |
| --- | --- | --- | --- |
| Landing (MazBtn, MazCard, MazBadge, MazAvatar, MazAccordion) | 103.2 kB (15.6 kB gzip) | 49.1 kB (8.8 kB gzip) | -52% |
| Sign in (MazInput, MazCheckbox, MazBtn, MazCard, MazLink, toast plugin) | 108.3 kB (16.0 kB gzip) | 64.7 kB (10.1 kB gzip) | -40% |
| Dashboard (MazTable, MazSelect, MazDatePicker, MazDialog, MazSidebar, MazTabs, MazDropdown, MazSwitch, toast, dialog, vTooltip...) | 156.1 kB (24.2 kB gzip) | 119.5 kB (19.4 kB gzip) | -23% |
| No Tailwind, with `maz-ui/utilities.css` (padded-container, text-display, rich-text, MazBtn, MazCard) | 118.8 kB (16.9 kB gzip) | 50.9 kB (8.4 kB gzip) | -57% |
| Every component | 212.0 kB (29.8 kB gzip) | 195.7 kB (28.0 kB gzip) | -8% |

The `style.css` of maz-ui alone goes from 86.9 kB to 32.8 kB (landing), 43.8 kB (sign in) and 50.3 kB (dashboard).

With Nuxt (2 pages using MazBtn, MazCard, MazBadge, LazyMazAccordion, MazInput, MazCheckbox, the toast plugin and vTooltip, `nuxi generate`), the CSS files go from 122.3 kB (21.0 kB gzip) to 78.6 kB (14.8 kB gzip) with the default `css.purge: true`, which is -36%.

**Warning: The numbers depend on your app**

They come from the demo apps above and this setup (preset, Tailwind or not, components used). The more components you use, the smaller the gain.

### Purge options

All options are optional.

| Option | Type | Description |
| --- | --- | --- |
| `content` | `string[]` | Globs of the files that use maz-ui, relative to the root of the project. Added to the defaults |
| `entries` | `string[]` | Entries of maz-ui to keep even if the plugin does not find them in the code: a component (`MazBtn`), a directive (`vTooltip`), a plugin (`plugins/toast`) |
| `safelist` | `(string \| RegExp)[]` | Classes to keep: `maz:` classes of the components or public utilities (`text-title-1`, `/^rich-text/`) |
| `report` | `boolean` | Print the CSS saved by the purge (default: `true`) |

By default, the plugin scans every source file of the project (`vue`, `js`, `jsx`, `ts`, `tsx`, `html`, `md`, `mdx`, `astro`, `svelte`...), and ignores `node_modules`, `dist`, `.output`, `.nuxt`, `coverage` and `.d.ts` files.

#### Monorepo

When your app uses components written in another package of the monorepo, add its sources:

```ts
MazUiPurgeCss({
  content: ['../../packages/ui/src/**/*.vue'],
})
```

#### Dependency built on maz-ui

The default scan ignores `node_modules`, the globs of `content` do not: add the files of a dependency that renders maz-ui components (a design system of your company), or list the entries it uses with `entries`:

```ts
MazUiPurgeCss({
  content: ['node_modules/@acme/ui/dist/**/*.js'],
  // or
  entries: ['MazBtn', 'MazDialog', 'plugins/toast', 'vTooltip'],
})
```

#### Names built at runtime

A component resolved from a dynamic name, or a class that only appears in HTML loaded at runtime (a CMS, an API), is not found in the source. Keep it explicitly:

```ts
MazUiPurgeCss({
  entries: ['MazBtn', 'MazCard'],
  safelist: ['text-title-1', /^rich-text/],
})
```

### Bundle check

At the end of the build, the plugin looks for the purged classes in the final JS and HTML. If one is found, a component of maz-ui is used by a file the plugin does not scan (a dependency, a package of your monorepo), and the build warns:

```txt
[maz-ui:purge-css] 3 purged classes are in the bundle: rounded-lg, flex, p-4
A component of maz-ui is probably used by a file the plugin does not scan (a dependency, a package of your monorepo).
Add its files to the `content` option, or the component to `entries`.
```

Fix it with `content` (the files that use the component) or `entries`, then rebuild.

### Projects without Tailwind

`maz-ui/utilities.css` contains the public utilities of maz-ui without prefix: the `text-*` and `type-*` type scale, `rich-text`, `padded-container`, `flex-center`, `glass`, `scrollbar-themed`, `disabled-*`, `cursor-interactive`, `cap-f` and `z-default-backdrop`. It weighs 19.7 kB (2.6 kB gzip) and the plugin purges it like `style.css`.

```ts
import 'maz-ui/style.css'
import 'maz-ui/utilities.css'
```

**Warning: With Tailwind CSS**

Keep `@import 'maz-ui/tailwindcss/utilities.css'` in your Tailwind entry and do not import `maz-ui/utilities.css`: you would get duplicates, and no variants (`hover:`, `tab-m:`...). See [Tailwind CSS](https://maz-ui.com/guide/tailwind.md).

### Limitations

- Vite only for now (no webpack, Rollup alone or other bundlers).
- Build only: the dev server keeps the whole CSS.
- Entries are found by name in the files of the project: names built at runtime need `entries` or `safelist`.
- Only the CSS of maz-ui is purged, not the CSS of your app.

## Theme presets

`getPreset` of `@maz-ui/themes` (used by the theme plugin, `useTheme` and `definePreset`) imports each named preset on demand: every preset is a chunk of your build, even the ones your app never loads. They are only downloaded when loaded, but a service worker that precaches every JS file (PWA) downloads all of them. `presets` keeps only the presets you list:

```ts
MazUi({
  presets: ['maz-ui', 'ocean'],
})
```

`presets` lists the presets your app loads by name: `theme.preset`, `updateTheme('ocean')`, `definePreset({ base: 'ocean' })`. `[]` keeps none, for an app that only uses preset objects. Without `presets`, every preset stays in the build. The plugin alone is `MazUiThemePresets({ presets })`.

The plugin also applies to the dev server, so a missing preset fails in dev as in production: `updateTheme('nova')` rejects with an error naming the option, and a `maz-preset` cookie with a removed preset falls back to the configured one with a warning. See [Presets in the build](https://maz-ui.com/ecosystem/themes.md#presets-in-the-build).
