1 | # @vue/component-compiler-utils [![Build Status](https://circleci.com/gh/vuejs/component-compiler-utils/tree/master.svg?style=shield)](https://circleci.com/gh/vuejs/component-compiler-utils/)
|
2 |
|
3 | > Lower level utilities for compiling Vue single file components
|
4 |
|
5 | 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](https://github.com/vuejs/vue-loader) version 15 and above.
|
6 |
|
7 | The API surface is intentionally minimal - the goal is to reuse as much as possible while being as flexible as possible.
|
8 |
|
9 | ## Why isn't `vue-template-compiler` a peerDependency?
|
10 |
|
11 | 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.
|
12 |
|
13 | 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.
|
14 |
|
15 | ## API
|
16 |
|
17 | ### parse(ParseOptions): SFCDescriptor
|
18 |
|
19 | 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.
|
20 |
|
21 | ``` ts
|
22 | interface ParseOptions {
|
23 | source: string
|
24 | filename?: string
|
25 | compiler: VueTemplateCompiler
|
26 | // https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilerparsecomponentfile-options
|
27 | // default: { pad: 'line' }
|
28 | compilerParseOptions?: VueTemplateCompilerParseOptions
|
29 | sourceRoot?: string
|
30 | needMap?: boolean
|
31 | }
|
32 |
|
33 | interface SFCDescriptor {
|
34 | template: SFCBlock | null
|
35 | script: SFCBlock | null
|
36 | styles: SFCBlock[]
|
37 | customBlocks: SFCCustomBlock[]
|
38 | }
|
39 |
|
40 | interface SFCCustomBlock {
|
41 | type: string
|
42 | content: string
|
43 | attrs: { [key: string]: string | true }
|
44 | start: number
|
45 | end: number
|
46 | map?: RawSourceMap
|
47 | }
|
48 |
|
49 | interface SFCBlock extends SFCCustomBlock {
|
50 | lang?: string
|
51 | src?: string
|
52 | scoped?: boolean
|
53 | module?: string | boolean
|
54 | }
|
55 | ```
|
56 |
|
57 | ### compileTemplate(TemplateCompileOptions): TemplateCompileResults
|
58 |
|
59 | 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.
|
60 |
|
61 | It can also optionally perform pre-processing for any templating engine supported by [consolidate](https://github.com/tj/consolidate.js/).
|
62 |
|
63 | ``` ts
|
64 | interface TemplateCompileOptions {
|
65 | source: string
|
66 | filename: string
|
67 |
|
68 | compiler: VueTemplateCompiler
|
69 | // https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilercompiletemplate-options
|
70 | // default: {}
|
71 | compilerOptions?: VueTemplateCompilerOptions
|
72 |
|
73 | // Template preprocessor
|
74 | preprocessLang?: string
|
75 | preprocessOptions?: any
|
76 |
|
77 | // Transform asset urls found in the template into `require()` calls
|
78 | // This is off by default. If set to true, the default value is
|
79 | // {
|
80 | // audio: 'src',
|
81 | // video: ['src', 'poster'],
|
82 | // source: 'src',
|
83 | // img: 'src',
|
84 | // image: ['xlink:href', 'href'],
|
85 | // use: ['xlink:href', 'href']
|
86 | // }
|
87 | transformAssetUrls?: AssetURLOptions | boolean
|
88 |
|
89 | // For vue-template-es2015-compiler, which is a fork of Buble
|
90 | transpileOptions?: any
|
91 |
|
92 | isProduction?: boolean // default: false
|
93 | isFunctional?: boolean // default: false
|
94 | optimizeSSR?: boolean // default: false
|
95 |
|
96 | // Whether prettify compiled render function or not (development only)
|
97 | // default: true
|
98 | prettify?: boolean
|
99 | }
|
100 |
|
101 | interface TemplateCompileResult {
|
102 | ast: Object | undefined
|
103 | code: string
|
104 | source: string
|
105 | tips: string[]
|
106 | errors: string[]
|
107 | }
|
108 |
|
109 | interface AssetURLOptions {
|
110 | [name: string]: string | string[]
|
111 | }
|
112 | ```
|
113 |
|
114 | #### Handling the Output
|
115 |
|
116 | The resulting JavaScript code will look like this:
|
117 |
|
118 | ``` js
|
119 | var render = function (h) { /* ... */}
|
120 | var staticRenderFns = [function (h) { /* ... */}, function (h) { /* ... */}]
|
121 | ```
|
122 |
|
123 | It **does NOT** assume any module system. It is your responsibility to handle the exports, if needed.
|
124 |
|
125 | ### compileStyle(StyleCompileOptions)
|
126 |
|
127 | 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.
|
128 |
|
129 | ``` ts
|
130 | interface StyleCompileOptions {
|
131 | source: string
|
132 | filename: string
|
133 | id: string
|
134 | map?: any
|
135 | scoped?: boolean
|
136 | trim?: boolean
|
137 | preprocessLang?: string
|
138 | preprocessOptions?: any
|
139 | postcssOptions?: any
|
140 | postcssPlugins?: any[]
|
141 | }
|
142 |
|
143 | interface StyleCompileResults {
|
144 | code: string
|
145 | map: any | void
|
146 | rawResult: LazyResult | void // raw lazy result from PostCSS
|
147 | errors: string[]
|
148 | }
|
149 | ```
|
150 |
|
151 | ### compileStyleAsync(StyleCompileOptions)
|
152 |
|
153 | Same as `compileStyle(StyleCompileOptions)` but it returns a Promise resolving to `StyleCompileResults`. It can be used with async postcss plugins.
|