0
# @vitejs/plugin-vue2
1

2
@vitejs/plugin-vue2 is a Vite plugin that provides Vue 2 Single File Component (SFC) support for Vite build tool. It compiles Vue 2 templates, handles asset URL transformations, and provides comprehensive options for configuring the Vue 2 compiler including script, template, and style compilation settings.
3

4
## Package Information
5

6
- **Package Name**: @vitejs/plugin-vue2
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vitejs/plugin-vue2`
10

11
## Core Imports
12

13
```typescript
14
import vue from '@vitejs/plugin-vue2';
15
import type { Options, VueQuery } from '@vitejs/plugin-vue2';
16
import { parseVueRequest } from '@vitejs/plugin-vue2';
17
```
18

19
For CommonJS:
20

21
```javascript
22
const vue = require('@vitejs/plugin-vue2');
23
const { parseVueRequest } = require('@vitejs/plugin-vue2');
24
```
25

26
## Basic Usage
27

28
```typescript
29
import vue from '@vitejs/plugin-vue2';
30

31
export default {
32
  plugins: [
33
    vue({
34
      include: /\.vue$/,
35
      template: {
36
        transformAssetUrls: {
37
          img: ['src'],
38
          video: ['src', 'poster']
39
        }
40
      }
41
    })
42
  ]
43
}
44
```
45

46
## Architecture
47

48
@vitejs/plugin-vue2 is built around several key components:
49

50
- **Plugin Factory**: Main function that creates a Vite plugin instance with Vue 2 SFC support
51
- **SFC Compiler Integration**: Interfaces with Vue 2.7+ compiler-sfc for component compilation
52
- **Asset URL Transformation**: Converts static asset references to ESM imports during template compilation
53
- **Hot Module Replacement**: Development-time component updates without page refresh
54
- **Multi-format Support**: Handles various preprocessors for templates, scripts, and styles
55

56
## Capabilities
57

58
### Plugin Factory Function
59

60
Creates a Vite plugin instance configured for Vue 2 SFC processing with customizable compilation options.
61

62
```typescript { .api }
63
/**
64
 * Creates a Vite plugin for Vue 2 Single File Component support
65
 * @param rawOptions - Configuration options for the plugin
66
 * @returns Vite Plugin instance with Vue 2 SFC processing capabilities
67
 */
68
function vue(rawOptions?: Options): Plugin;
69

70
interface Options {
71
  /** Files to include for processing (default: /\.vue$/) */
72
  include?: string | RegExp | (string | RegExp)[];
73
  /** Files to exclude from processing */
74
  exclude?: string | RegExp | (string | RegExp)[];
75
  /** Production mode flag (auto-detected if not specified) */
76
  isProduction?: boolean;
77
  /** Script compilation options */
78
  script?: Partial<Pick<SFCScriptCompileOptions, 'babelParserPlugins'>>;
79
  /** Template compilation options */
80
  template?: Partial<Pick<SFCTemplateCompileOptions, 
81
    | 'compiler'
82
    | 'compilerOptions'
83
    | 'preprocessOptions'
84
    | 'transpileOptions'
85
    | 'transformAssetUrls'
86
    | 'transformAssetUrlsOptions'
87
  >>;
88
  /** Style compilation options */
89
  style?: Partial<Pick<SFCStyleCompileOptions, 'trim'>>;
90
  /** Custom Vue compiler instance (defaults to auto-resolved vue/compiler-sfc) */
91
  compiler?: typeof _compiler;
92
}
93

94
interface ResolvedOptions extends Options {
95
  /** Resolved Vue compiler instance (required) */
96
  compiler: typeof _compiler;
97
  /** Project root directory */
98
  root: string;
99
  /** Source map generation flag */
100
  sourceMap: boolean;
101
  /** CSS dev source map flag */
102
  cssDevSourcemap: boolean;  
103
  /** Vite dev server instance */
104
  devServer?: ViteDevServer;
105
  /** Vue devtools support flag */
106
  devToolsEnabled?: boolean;
107
}
108
```
109

110
### Vue Request Parser
111

112
Utility function for parsing Vue-specific request URLs to extract filename and query parameters used internally by the plugin.
113

114
```typescript { .api }
115
/**
116
 * Parses Vue request URLs to extract filename and query parameters
117
 * @param id - Request URL string
118
 * @returns Object containing filename and parsed query parameters
119
 */
120
function parseVueRequest(id: string): {
121
  filename: string;
122
  query: VueQuery;
123
};
124

125
interface VueQuery {
126
  /** Vue file processing flag */
127
  vue?: boolean;
128
  /** Source path reference for external file blocks */
129
  src?: string;
130
  /** Block type for SFC processing */
131
  type?: 'script' | 'template' | 'style' | 'custom';
132
  /** Block index for multiple blocks of same type */
133
  index?: number;
134
  /** Language/preprocessor identifier */
135
  lang?: string;
136
  /** Raw content flag bypassing transformations */
137
  raw?: boolean;
138
  /** Scoped CSS processing flag */
139
  scoped?: boolean;
140
}
141
```
142

143
### Vue SFC Types
144

145
For TypeScript users working with Vue SFC components, these types from `vue/compiler-sfc` are commonly used:
146

147
```typescript { .api }
148
// Import Vue SFC types for advanced usage
149
import type {
150
  SFCDescriptor,
151
  SFCBlock,
152
  SFCScriptBlock,
153
  SFCTemplateBlock,
154
  SFCStyleBlock,
155
  SFCScriptCompileOptions,
156
  SFCTemplateCompileOptions,
157
  SFCStyleCompileOptions
158
} from 'vue/compiler-sfc';
159
```
160

161
## Configuration Examples
162

163
### Basic Configuration
164

165
```typescript
166
import vue from '@vitejs/plugin-vue2';
167

168
export default {
169
  plugins: [vue()]
170
}
171
```
172

173
### Advanced Configuration
174

175
```typescript
176
import vue from '@vitejs/plugin-vue2';
177

178
export default {
179
  plugins: [
180
    vue({
181
      include: [/\.vue$/, /\.md$/],
182
      exclude: /node_modules/,
183
      template: {
184
        compilerOptions: {
185
          whitespace: 'condense'
186
        },
187
        transformAssetUrls: {
188
          video: ['src', 'poster'],
189
          source: ['src'],
190
          img: ['src'],
191
          image: ['xlink:href', 'href'],
192
          use: ['xlink:href', 'href']
193
        }
194
      },
195
      script: {
196
        babelParserPlugins: ['decorators-legacy']
197
      }
198
    })
199
  ]
200
}
201
```
202

203
### Custom Block Processing
204

205
```typescript
206
import vue from '@vitejs/plugin-vue2';
207

208
const vueI18nPlugin = {
209
  name: 'vue-i18n',
210
  transform(code, id) {
211
    if (!/vue&type=i18n/.test(id)) {
212
      return;
213
    }
214
    if (/\.ya?ml$/.test(id)) {
215
      code = JSON.stringify(require('js-yaml').load(code.trim()));
216
    }
217
    return `export default Comp => {
218
      Comp.i18n = ${code}
219
    }`;
220
  }
221
};
222

223
export default {
224
  plugins: [vue(), vueI18nPlugin]
225
}
226
```
227

228
## Asset URL Transformation
229

230
The plugin automatically transforms asset URLs in Vue templates to ES module imports:
231

232
**Template:**
233
```vue
234
<template>
235
  <img src="../assets/logo.png" />
236
  <video poster="../assets/thumbnail.jpg">
237
    <source src="../assets/video.mp4" />
238
  </video>
239
</template>
240
```
241

242
**Transforms to:**
243
```vue
244
<script>
245
import _imports_0 from '../assets/logo.png';
246
import _imports_1 from '../assets/thumbnail.jpg';
247
import _imports_2 from '../assets/video.mp4';
248
</script>
249

250
<template>
251
  <img :src="_imports_0" />
252
  <video :poster="_imports_1">
253
    <source :src="_imports_2" />
254
  </video>
255
</template>
256
```
257

258
## TypeScript Support
259

260
The plugin fully supports TypeScript in Vue components:
261

262
```vue
263
<template>
264
  <div>{{ greeting }}</div>
265
</template>
266

267
<script lang="ts">
268
import { defineComponent } from 'vue';
269

270
interface User {
271
  name: string;
272
  age: number;
273
}
274

275
export default defineComponent({
276
  data(): { user: User } {
277
    return {
278
      user: { name: 'Alice', age: 25 }
279
    };
280
  },
281
  computed: {
282
    greeting(): string {
283
      return `Hello, ${this.user.name}!`;
284
    }
285
  }
286
});
287
</script>
288
```
289

290
## Scoped CSS and CSS Modules
291

292
### Scoped CSS
293

294
```vue
295
<template>
296
  <div class="container">
297
    <p class="text">Scoped styles</p>
298
  </div>
299
</template>
300

301
<style scoped>
302
.container {
303
  background: #f0f0f0;
304
}
305
.text {
306
  color: #333;
307
}
308
</style>
309
```
310

311
### CSS Modules
312

313
```vue
314
<template>
315
  <div :class="$style.container">
316
    <p :class="$style.text">CSS Modules</p>
317
  </div>
318
</template>
319

320
<style module>
321
.container {
322
  background: #f0f0f0;
323
}
324
.text {
325
  color: #333;
326
}
327
</style>
328
```
329

330
## Hot Module Replacement
331

332
The plugin provides seamless HMR support during development:
333

334
- **Template-only changes**: Fast re-render without losing component state
335
- **Script changes**: Component reload with state preservation where possible
336
- **Style changes**: Instant style updates without page refresh
337

338
## Requirements
339

340
- **Vue**: ^2.7.0 (peer dependency - Vue 2.7+ with Composition API support required)
341
- **Vite**: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 (peer dependency)
342
- **Node.js**: ^14.18.0 || >= 16.0.0
343

344
**Note**: Both Vue and Vite must be installed as peer dependencies. The plugin will automatically resolve the Vue compiler from your project's dependencies.
345

346
```bash
347
npm install vue@^2.7.0 vite@^5.0.0 @vitejs/plugin-vue2
348
```