1 | # vue-loader [![Build Status](https://circleci.com/gh/vuejs/vue-loader/tree/master.svg?style=shield)](https://circleci.com/gh/vuejs/vue-loader/tree/master) [![Windows Build status](https://ci.appveyor.com/api/projects/status/8cdonrkbg6m4k1tm/branch/master?svg=true)](https://ci.appveyor.com/project/yyx990803/vue-loader/branch/master)
|
2 |
|
3 | > webpack loader for Vue Single-File Components
|
4 |
|
5 | **NOTE:** The master branch now hosts the code for v15! Legacy code is now in the [v14 branch](https://github.com/vuejs/vue-loader/tree/v14).
|
6 |
|
7 | - [Documentation](https://vue-loader.vuejs.org)
|
8 | - [Migrating from v14](https://vue-loader.vuejs.org/migrating.html)
|
9 |
|
10 | ## What is Vue Loader?
|
11 |
|
12 | `vue-loader` is a loader for [webpack](https://webpack.js.org/) that allows you to author Vue components in a format called [Single-File Components (SFCs)](./docs/spec.md):
|
13 |
|
14 | ``` vue
|
15 | <template>
|
16 | <div class="example">{{ msg }}</div>
|
17 | </template>
|
18 |
|
19 | <script>
|
20 | export default {
|
21 | data () {
|
22 | return {
|
23 | msg: 'Hello world!'
|
24 | }
|
25 | }
|
26 | }
|
27 | </script>
|
28 |
|
29 | <style>
|
30 | .example {
|
31 | color: red;
|
32 | }
|
33 | </style>
|
34 | ```
|
35 |
|
36 | There are many cool features provided by `vue-loader`:
|
37 |
|
38 | - Allows using other webpack loaders for each part of a Vue component, for example Sass for `<style>` and Pug for `<template>`;
|
39 | - Allows custom blocks in a `.vue` file that can have custom loader chains applied to them;
|
40 | - Treat static assets referenced in `<style>` and `<template>` as module dependencies and handle them with webpack loaders;
|
41 | - Simulate scoped CSS for each component;
|
42 | - State-preserving hot-reloading during development.
|
43 |
|
44 | In a nutshell, the combination of webpack and `vue-loader` gives you a modern, flexible and extremely powerful front-end workflow for authoring Vue.js applications.
|
45 |
|
46 | ## How It Works
|
47 |
|
48 | > The following section is for maintainers and contributors who are interested in the internal implementation details of `vue-loader`, and is **not** required knowledge for end users.
|
49 |
|
50 | `vue-loader` is not a simple source transform loader. It handles each language blocks inside an SFC with its own dedicated loader chain (you can think of each block as a "virtual module"), and finally assembles the blocks together into the final module. Here's a brief overview of how the whole thing works:
|
51 |
|
52 | 1. `vue-loader` parses the SFC source code into an *SFC Descriptor* using `@vue/component-compiler-utils`. It then generates an import for each language block so the actual returned module code looks like this:
|
53 |
|
54 | ``` js
|
55 | // code returned from the main loader for 'source.vue'
|
56 |
|
57 | // import the <template> block
|
58 | import render from 'source.vue?vue&type=template'
|
59 | // import the <script> block
|
60 | import script from 'source.vue?vue&type=script'
|
61 | export * from 'source.vue?vue&type=script'
|
62 | // import <style> blocks
|
63 | import 'source.vue?vue&type=style&index=1'
|
64 |
|
65 | script.render = render
|
66 | export default script
|
67 | ```
|
68 |
|
69 | Notice how the code is importing `source.vue` itself, but with different request queries for each block.
|
70 |
|
71 | 2. We want the content in `script` block to be treated like `.js` files (and if it's `<script lang="ts">`, we want to to be treated like `.ts` files). Same for other language blocks. So we want webpack to apply any configured module rules that matches `.js` also to requests that look like `source.vue?vue&type=script`. This is what `VueLoaderPlugin` (`src/plugins.ts`) does: for each module rule in the webpack config, it creates a modified clone that targets corresponding Vue language block requests.
|
72 |
|
73 | Suppose we have configured `babel-loader` for all `*.js` files. That rule will be cloned and applied to Vue SFC `<script>` blocks as well. Internally to webpack, a request like
|
74 |
|
75 | ``` js
|
76 | import script from 'source.vue?vue&type=script'
|
77 | ```
|
78 |
|
79 | Will expand to:
|
80 |
|
81 | ``` js
|
82 | import script from 'babel-loader!vue-loader!source.vue?vue&type=script'
|
83 | ```
|
84 |
|
85 | Notice the `vue-loader` is also matched because `vue-loader` are applied to `.vue` files.
|
86 |
|
87 | Similarly, if you have configured `style-loader` + `css-loader` + `sass-loader` for `*.scss` files:
|
88 |
|
89 | ``` html
|
90 | <style scoped lang="scss">
|
91 | ```
|
92 |
|
93 | Will be returned by `vue-loader` as:
|
94 |
|
95 | ``` js
|
96 | import 'source.vue?vue&type=style&index=1&scoped&lang=scss'
|
97 | ```
|
98 |
|
99 | And webpack will expand it to:
|
100 |
|
101 | ``` js
|
102 | import 'style-loader!css-loader!sass-loader!vue-loader!source.vue?vue&type=style&index=1&scoped&lang=scss'
|
103 | ```
|
104 |
|
105 | 3. When processing the expanded requests, the main `vue-loader` will get invoked again. This time though, the loader notices that the request has queries and is targeting a specific block only. So it selects (`src/select.ts`) the inner content of the target block and passes it on to the loaders matched after it.
|
106 |
|
107 | 4. For the `<script>` block, this is pretty much it. For `<template>` and `<style>` blocks though, a few extra tasks need to be performed:
|
108 |
|
109 | - We need to compile the template using the Vue template compiler;
|
110 | - We need to post-process the CSS in `<style scoped>` blocks, **before** `css-loader`.
|
111 |
|
112 | Technically, these are additional loaders (`src/templateLoader.ts` and `src/stylePostLoader.ts`) that need to be injected into the expanded loader chain. It would be very complicated if the end users have to configure this themselves, so `VueLoaderPlugin` also injects a global [Pitching Loader](https://webpack.js.org/api/loaders/#pitching-loader) (`src/pitcher.ts`) that intercepts Vue `<template>` and `<style>` requests and injects the necessary loaders. The final requests look like the following:
|
113 |
|
114 | ``` js
|
115 | // <template lang="pug">
|
116 | import 'vue-loader/template-loader!pug-loader!vue-loader!source.vue?vue&type=template'
|
117 |
|
118 | // <style scoped lang="scss">
|
119 | import 'style-loader!css-loader!vue-loader/style-post-loader!sass-loader!vue-loader!source.vue?vue&type=style&index=1&scoped&lang=scss'
|
120 | ```
|