@vue/component-compiler-utils

Lower level utilities for compiling Vue single file components

This package contains lower level utilities that you can use if you are writing a plugin / transform for a bundler or module system that compiles Vue single file components into JavaScript. It is used in vue-loader version 15 and above.

The API surface is intentionally minimal - the goal is to reuse as much as possible while being as flexible as possible.

Why isn't vue-template-compiler a peerDependency?

Since this package is more often used as a low-level utility, it is usually a transitive dependency in an actual Vue project. It is therefore the responsibility of the higher-level package (e.g. vue-loader) to inject vue-template-compiler via options when calling the parse and compileTemplate methods.

Not listing it as a peer depedency also allows tooling authors to use a non-default template compiler instead of vue-template-compiler without having to include it just to fullfil the peer dep requirement.

API

parse(ParseOptions): SFCDescriptor

Parse raw single file component source into a descriptor with source maps. The actual compiler (vue-template-compiler) must be passed in via the compiler option so that the specific version used can be determined by the end user.

1interface ParseOptions {
2  source: string
3  filename?: string
4  compiler: VueTemplateCompiler
5  // https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilerparsecomponentfile-options
6  // defualt: { pad: 'line' }
7  compilerParseOptions?: VueTemplateCompilerParseOptions
8  sourceRoot?: string
9  needMap?: boolean
10}
11
12interface SFCDescriptor {
13  template: SFCBlock | null
14  script: SFCBlock | null
15  styles: SFCBlock[]
16  customBlocks: SFCCustomBlock[]
17}
18
19interface SFCCustomBlock {
20  type: string
21  content: string
22  attrs: { [key: string]: string | true }
23  start: number
24  end: number
25  map?: RawSourceMap
26}
27
28interface SFCBlock extends SFCCustomBlock {
29  lang?: string
30  src?: string
31  scoped?: boolean
32  module?: string | boolean
33}

compileTemplate(TemplateCompileOptions): TemplateCompileResults

Takes raw template source and compile it into JavaScript code. The actual compiler (vue-template-compiler) must be passed in via the compiler option so that the specific version used can be determined by the end user.

It can also optionally perform pre-processing for any templating engine supported by consolidate.

1interface TemplateCompileOptions {
2  source: string
3  filename: string
4
5  compiler: VueTemplateCompiler
6  https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilercompiletemplate-options
7  // default: {}
8  compilerOptions?: VueTemplateCompilerOptions
9
10  // Template preprocessor
11  preprocessLang?: string
12  preprocessOptions?: any
13
14  // Transform asset urls found in the template into `require()` calls
15  // This is off by default. If set to true, the default value is
16  // {
17  //   video: ['src', 'poster'],
18  //   source: 'src',
19  //   img: 'src',
20  //   image: 'xlink:href'
21  // }
22  transformAssetUrls?: AssetURLOptions | boolean
23
24  // For vue-template-es2015-compiler, which is a fork of Buble
25  transpileOptions?: any
26
27  isProduction?: boolean  // default: false
28  isFunctional?: boolean  // default: false
29  optimizeSSR?: boolean   // default: false
30}
31
32interface TemplateCompileResult {
33  code: string
34  source: string
35  tips: string[]
36  errors: string[]
37}
38
39interface AssetURLOptions {
40  [name: string]: string | string[]
41}

Handling the Output

The resulting JavaScript code will look like this:

1var render = function (h) { /* ... */}
2var staticRenderFns = [function (h) { /* ... */}, function (h) { /* ... */}]

It does NOT assume any module system. It is your responsibility to handle the exports, if needed.

compileStyle(StyleCompileOptions)

Take input raw CSS and applies scoped CSS transform. It does NOT handle pre-processors. If the component doesn't use scoped CSS then this step can be skipped.

1interface StyleCompileOptions {
2  source: string
3  filename: string
4  id: string
5  map?: any
6  scoped?: boolean
7  trim?: boolean
8  preprocessLang?: string
9  preprocessOptions?: any
10  postcssOptions?: any
11  postcssPlugins?: any[]
12}
13
14interface StyleCompileResults {
15  code: string
16  map: any | void
17  rawResult: LazyResult | void // raw lazy result from PostCSS
18  errors: string[]
19}

compileStyleAsync(StyleCompileOptions)

Same as compileStyle(StyleCompileOptions) but it returns a Promise resolving to StyleCompileResults. It can be used with async postcss plugins.