0
# Vite Plugin Vuetify
1

2
Vite Plugin Vuetify is a Vite plugin that provides tree-shaking optimization for Vuetify 3 components and automatic import functionality. It enables automatic imports of Vuetify components and directives while providing flexible style customization options including SASS variable overrides and conditional style imports.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-vuetify
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite-plugin-vuetify`
10

11
## Core Imports
12

13
```typescript
14
import vuetify, { transformAssetUrls } from "vite-plugin-vuetify";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const vuetify = require("vite-plugin-vuetify").default;
21
const { transformAssetUrls } = require("vite-plugin-vuetify");
22
```
23

24
## Basic Usage
25

26
```typescript
27
// vite.config.js
28
import { defineConfig } from "vite";
29
import vue from "@vitejs/plugin-vue";
30
import vuetify, { transformAssetUrls } from "vite-plugin-vuetify";
31

32
export default defineConfig({
33
  plugins: [
34
    vue({
35
      template: { transformAssetUrls }
36
    }),
37
    vuetify({
38
      autoImport: true,
39
      styles: true
40
    })
41
  ]
42
});
43
```
44

45
```javascript
46
// plugins/vuetify.js
47
import "vuetify/styles";
48
import { createVuetify } from "vuetify";
49

50
export default createVuetify();
51
```
52

53
## Capabilities
54

55
### Main Plugin Function
56

57
Creates a Vite plugin configuration for Vuetify optimization.
58

59
```typescript { .api }
60
/**
61
 * Creates Vite plugins for Vuetify component optimization and style processing
62
 * @param options - Configuration options for the plugin
63
 * @returns Array of Vite Plugin instances
64
 */
65
declare function vuetify(options?: Options): Plugin[];
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
// Basic usage with default options
72
vuetify()
73

74
// Enable labs components and ignore specific components
75
vuetify({
76
  autoImport: {
77
    labs: true,
78
    ignore: ["VAlert", "Ripple"]
79
  }
80
})
81

82
// Custom SASS configuration
83
vuetify({
84
  styles: {
85
    configFile: "src/settings.scss"
86
  }
87
})
88

89
// Disable all style imports
90
vuetify({ styles: "none" })
91

92
// Use SASS source files instead of CSS
93
vuetify({ styles: "sass" })
94
```
95

96
### Asset URL Transformation
97

98
Provides configuration for transforming asset URLs in Vuetify component templates.
99

100
```typescript { .api }
101
/**
102
 * Configuration object for transforming asset URLs in Vuetify components
103
 * Used with @vitejs/plugin-vue for proper asset handling
104
 */
105
declare const transformAssetUrls: Record<string, string[]>;
106
```
107

108
**Static Property:**
109

110
```typescript { .api }
111
/**
112
 * Static property on the main vuetify function providing asset URL transformation config
113
 */
114
declare namespace vuetify {
115
  const transformAssetUrls: Record<string, string[]>;
116
}
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
// With @vitejs/plugin-vue
123
import vue from "@vitejs/plugin-vue";
124
import vuetify, { transformAssetUrls } from "vite-plugin-vuetify";
125

126
export default defineConfig({
127
  plugins: [
128
    vue({
129
      template: { transformAssetUrls }
130
    }),
131
    vuetify()
132
  ]
133
});
134

135
// Using static property
136
vue({
137
  template: { transformAssetUrls: vuetify.transformAssetUrls }
138
})
139
```
140

141
## Configuration Types
142

143
### Options Interface
144

145
Main configuration interface for the Vuetify plugin.
146

147
```typescript { .api }
148
interface Options {
149
  /** Controls automatic import behavior for Vuetify components and directives */
150
  autoImport?: ImportPluginOptions;
151
  /** Controls style loading and processing behavior */
152
  styles?: StylesOptions;
153
}
154
```
155

156
### Import Plugin Options
157

158
Configuration for automatic import functionality.
159

160
```typescript { .api }
161
/** Configuration for auto-import functionality */
162
type ImportPluginOptions = boolean | ObjectImportPluginOptions;
163

164
interface ObjectImportPluginOptions {
165
  /** Include Vuetify Labs components in auto-imports */
166
  labs?: boolean;
167
  /** Array of component or directive names to ignore during auto-import */
168
  ignore?: (keyof typeof Components | keyof typeof Directives)[];
169
}
170
```
171

172
### Styles Options
173

174
Configuration for style loading and processing.
175

176
```typescript { .api }
177
/** Style loading configuration */
178
type StylesOptions = 
179
  | true                          // Load default CSS styles
180
  | "none"                        // Disable all style imports
181
  | "sass"                        // Use SASS source files instead of CSS
182
  | StylesConfigObject;           // Custom SASS configuration
183

184
interface StylesConfigObject {
185
  /** Path to SASS configuration file for variable overrides */
186
  configFile: string;
187
}
188
```
189

190
## Plugin Architecture
191

192
The vuetify function returns an array containing up to two Vite plugins:
193

194
1. **Import Plugin** (`vuetify:import`) - Handles automatic component and directive imports
195
2. **Styles Plugin** (`vuetify:styles`) - Processes style imports and SASS configuration
196

197
**Import Plugin Features:**
198
- Automatic detection of Vuetify components and directives in Vue templates
199
- Tree-shaking support for optimal bundle size
200
- Labs component support
201
- Selective component/directive ignoring
202

203
**Styles Plugin Features:**
204
- CSS to SASS file resolution
205
- Custom SASS variable configuration
206
- Virtual module handling for custom styles
207
- Support for different style loading modes
208

209
## Error Handling
210

211
The plugin will throw errors in the following cases:
212

213
- When Vuetify plugin is loaded before the Vue plugin (import plugin will throw)
214
- When SASS configuration file is not accessible
215
- When invalid style configuration is provided
216

217
## TypeScript Support
218

219
The plugin provides full TypeScript support with:
220
- Complete type definitions for all configuration options
221
- Generic type preservation in internal APIs
222
- Integration with Vuetify's component and directive types
223
- Proper inference for import and style options
224

225
## Asset URL Transformation Details
226

227
The `transformAssetUrls` configuration includes mappings for Vuetify components that use image assets:
228

229
- **VAppBar**: `['image']`
230
- **VAvatar**: `['image']`  
231
- **VCard**: `['image', 'prependAvatar', 'appendAvatar']`
232
- **VImg**: `['src', 'lazySrc', 'srcset']`
233
- **VParallax**: `['src', 'lazySrc', 'srcset']`
234
- And many more component-to-attribute mappings
235

236
This ensures proper asset URL resolution for both kebab-case and PascalCase component names.