vue-compiler-sfc-plugin

This package is a Vue 3 compatible helper that wraps @vue/compiler-sfc and provides build-time integration hooks. For pull requests please see the Vue 3 core repository.

This package can be used to integrate Vue 3 SFC (Single File Component) compilation into custom build pipelines. In most cases you should be using it with @vitejs/plugin-vue or vue-loader, you will only need it separately if you are writing build tools with very specific needs.

Installation

npm install vue-compiler-sfc-plugin

const { parse, compileTemplate, compileScript, compileStyleAsync } = require('@vue/compiler-sfc')

Version Compatibility

This package requires Vue >=3.0.0. The version of this package follows Vue 3's minor releases to indicate compatibility.

| vue-compiler-sfc-plugin | Vue 3 | |------------------------|-------| | 3.5.x | ^3.5.0 | | 3.4.x | ^3.4.0 |

API

This package re-exports and extends @vue/compiler-sfc. For the full API reference, see the @vue/compiler-sfc documentation.

parse(source, options)

Parse a Vue SFC source string into a descriptor object:

const { parse } = require('@vue/compiler-sfc')

const { descriptor, errors } = parse(`
  <template>
    <div>Hello</div>
  </template>

  <script>
  export default {}
  </script>
`)

The returned descriptor is an SFCDescriptor object with the following structure:

{
  filename: string,
  source: string,
  template: SFCTemplateBlock | null,
  script: SFCScriptBlock | null,
  scriptSetup: SFCScriptBlock | null,
  styles: SFCStyleBlock[],
  customBlocks: SFCBlock[],
  cssVars: string[],
  slotted: boolean,
  shouldForceReload: (prevImports: Record<string, ImportBinding>) => boolean
}

compileTemplate(options)

Compile the <template> block of an SFC into a render function:

const { compileTemplate } = require('@vue/compiler-sfc')

const { code, errors } = compileTemplate({
  source: `<div>Hello</div>`,
  filename: 'example.vue',
  id: 'data-v-xxxxxx'
})

Options

• source — Template source string (required)
• filename — Used for error messages (required)
• id — Scope ID for CSS scoping (required)
• scoped — Whether to generate scoped CSS attribute (boolean, default false)
• isProd — Optimize output for production (boolean, default false)
• ssr — Compile to SSR render function (boolean, default false)
• ssrCssVars — CSS variable bindings for SSR (string[])
• compilerOptions — Options passed to the underlying @vue/compiler-dom

compileScript(descriptor, options)

Compile the <script> or <script setup> block of an SFC:

const { compileScript } = require('@vue/compiler-sfc')

const scriptBlock = compileScript(descriptor, {
  id: 'data-v-xxxxxx'
})

Returns an SFCScriptBlock with the compiled content and inferred bindings.

compileStyleAsync(options)

Compile a <style> block asynchronously, with support for CSS Modules and scoped styles:

const { compileStyleAsync } = require('@vue/compiler-sfc')

const result = await compileStyleAsync({
  source: `.foo { color: red; }`,
  filename: 'example.vue',
  id: 'data-v-xxxxxx',
  scoped: true,
  modules: false
})

generateCodeFrame(source, start, end)

Generate a code frame highlighting a range in the source string. Useful for error reporting in higher-level tooling:

const { generateCodeFrame } = require('@vue/compiler-sfc')

const frame = generateCodeFrame(source, start, end)
// Returns a string with the highlighted code range

Usage with Vite

When using Vite, @vitejs/plugin-vue handles SFC compilation automatically. This package is only needed if you are building custom Vite plugins or tooling that processes .vue files directly.

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [vue()]
}

Usage with webpack

When using webpack with Vue 3, use vue-loader@17+:

// webpack.config.js
const { VueLoaderPlugin } = require('vue-loader')

module.exports = {
  plugins: [new VueLoaderPlugin()],
  module: {
    rules: [
      { test: /\.vue$/, loader: 'vue-loader' }
    ]
  }
}

License

MIT