@vitejs/plugin-vue

Note: as of vue 3.2.13+ and @vitejs/plugin-vue 1.9.0+, @vue/compiler-sfc is no longer required as a peer dependency.

1// vite.config.js
2import vue from '@vitejs/plugin-vue'
3
4export default {
5  plugins: [vue()],
6}

For JSX / TSX support, @vitejs/plugin-vue-jsx is also needed.

Options

1export interface Options {
2  include?: string | RegExp | (string | RegExp)[]
3  exclude?: string | RegExp | (string | RegExp)[]
4
5  isProduction?: boolean
6
7  /**
8   * Requires @vitejs/plugin-vue@^5.1.0
9   */
10  features?: {
11    /**
12     * Enable reactive destructure for `defineProps`.
13     * - Available in Vue 3.4 and later.
14     * - **default:** `false` in Vue 3.4 (**experimental**), `true` in Vue 3.5+
15     */
16    propsDestructure?: boolean
17    /**
18     * Transform Vue SFCs into custom elements.
19     * - `true`: all `*.vue` imports are converted into custom elements
20     * - `string | RegExp`: matched files are converted into custom elements
21     * - **default:** /\.ce\.vue$/
22     */
23    customElement?: boolean | string | RegExp | (string | RegExp)[]
24    /**
25     * Set to `false` to disable Options API support and allow related code in
26     * Vue core to be dropped via dead-code elimination in production builds,
27     * resulting in smaller bundles.
28     * - **default:** `true`
29     */
30    optionsAPI?: boolean
31    /**
32     * Set to `true` to enable devtools support in production builds.
33     * Results in slightly larger bundles.
34     * - **default:** `false`
35     */
36    prodDevtools?: boolean
37    /**
38     * Set to `true` to enable detailed information for hydration mismatch
39     * errors in production builds. Results in slightly larger bundles.
40     * - **default:** `false`
41     */
42    prodHydrationMismatchDetails?: boolean
43    /**
44     * Customize the component ID generation strategy.
45     * - `'filepath'`: hash the file path (relative to the project root)
46     * - `'filepath-source'`: hash the file path and the source code
47     * - `function`: custom function that takes the file path, source code,
48     *   whether in production mode, and the default hash function as arguments
49     * - **default:** `'filepath'` in development, `'filepath-source'` in production
50     */
51    componentIdGenerator?:
52      | 'filepath'
53      | 'filepath-source'
54      | ((
55          filepath: string,
56          source: string,
57          isProduction: boolean | undefined,
58          getHash: (text: string) => string,
59        ) => string)
60  }
61
62  // `script`, `template` and `style` are lower-level compiler options
63  // to pass on to respective APIs of `vue/compiler-sfc`
64
65  script?: Partial<
66    Omit<
67      SFCScriptCompileOptions,
68      | 'id'
69      | 'isProd'
70      | 'inlineTemplate'
71      | 'templateOptions'
72      | 'sourceMap'
73      | 'genDefaultAs'
74      | 'customElement'
75    >
76  >
77
78  template?: Partial<
79    Omit<
80      SFCTemplateCompileOptions,
81      | 'id'
82      | 'source'
83      | 'ast'
84      | 'filename'
85      | 'scoped'
86      | 'slotted'
87      | 'isProd'
88      | 'inMap'
89      | 'ssr'
90      | 'ssrCssVars'
91      | 'preprocessLang'
92    >
93  >
94
95  style?: Partial<
96    Omit<
97      SFCStyleCompileOptions,
98      | 'filename'
99      | 'id'
100      | 'isProd'
101      | 'source'
102      | 'scoped'
103      | 'cssDevSourcemap'
104      | 'postcssOptions'
105      | 'map'
106      | 'postcssPlugins'
107      | 'preprocessCustomRequire'
108      | 'preprocessLang'
109      | 'preprocessOptions'
110    >
111  >
112
113  /**
114   * Use custom compiler-sfc instance. Can be used to force a specific version.
115   */
116  compiler?: typeof _compiler
117
118  /**
119   * @deprecated moved to `features.customElement`.
120   */
121  customElements?: boolean | string | RegExp | (string | RegExp)[]
122}

Asset URL handling

When @vitejs/plugin-vue compiles the <template> blocks in SFCs, it also converts any encountered asset URLs into ESM imports.

For example, the following template snippet:

1<img src="../image.png" />

Is the same as:

1<script setup>
2import _imports_0 from '../image.png'
3</script>
4
5<img :src="_imports_0" />

By default the following tag/attribute combinations are transformed, and can be configured using the template.transformAssetUrls option.

1{
2  video: ['src', 'poster'],
3  source: ['src'],
4  img: ['src'],
5  image: ['xlink:href', 'href'],
6  use: ['xlink:href', 'href']
7}

Note that only attribute values that are static strings are transformed. Otherwise, you'd need to import the asset manually, e.g. import imgUrl from '../image.png'.

Example for passing options to vue/compiler-sfc:

1import vue from '@vitejs/plugin-vue'
2
3export default {
4  plugins: [
5    vue({
6      template: {
7        compilerOptions: {
8          // ...
9        },
10        transformAssetUrls: {
11          // ...
12        },
13      },
14    }),
15  ],
16}

Example for transforming custom blocks

1import vue from '@vitejs/plugin-vue'
2import yaml from 'js-yaml'
3
4const vueI18nPlugin = {
5  name: 'vue-i18n',
6  transform(code, id) {
7    // if .vue file don't have <i18n> block, just return
8    if (!/vue&type=i18n/.test(id)) {
9      return
10    }
11    // parse yaml
12    if (/\.ya?ml$/.test(id)) {
13      code = JSON.stringify(yaml.load(code.trim()))
14    }
15    // mount the value on the i18n property of the component instance
16    return `export default Comp => {
17      Comp.i18n = ${code}
18    }`
19  },
20}
21
22export default {
23  plugins: [vue(), vueI18nPlugin],
24}

Create a file named Demo.vue, add lang="yaml" to the <i18n> blocks, then you can use the syntax of YAML:

1<template>Hello</template>
2
3<i18n lang="yaml">
4message: 'world'
5fullWord: 'hello world'
6</i18n>

message is mounted on the i18n property of the component instance, you can use like this:

1<script setup lang="ts">
2import Demo from 'components/Demo.vue'
3</script>
4
5<template>
6  <Demo /> {{ Demo.i18n.message }}
7  <div>{{ Demo.i18n.fullWord }}</div>
8</template>

Using Vue SFCs as Custom Elements

Requires vue@^3.2.0 & @vitejs/plugin-vue@^1.4.0

Vue 3.2 introduces the defineCustomElement method, which works with SFCs. By default, <style> tags inside SFCs are extracted and merged into CSS files during build. However when shipping a library of custom elements, it may be desirable to inline the styles as JavaScript strings and inject them into the custom elements' shadow root instead.

Starting in 1.4.0, files ending with *.ce.vue will be compiled in "custom elements" mode: its <style> tags are compiled into inlined CSS strings and attached to the component as its styles property:

1import { defineCustomElement } from 'vue'
2import Example from './Example.ce.vue'
3
4console.log(Example.styles) // ['/* css content */']
5
6// register
7customElements.define('my-example', defineCustomElement(Example))

Note in custom elements mode there is no need to use <style scoped> since the CSS is already scoped inside the shadow DOM.

The customElement plugin option can be used to configure the behavior:

• { customElement: true } will import all *.vue files in custom element mode.
• Use a string or regex pattern to change how files should be loaded as Custom Elements (this check is applied after include and exclude matches).

License

MIT