Skip to content

Commit 759b07d

Browse files
committed
chore: add How It Workds to README [ci skip]
1 parent 9f75bf3 commit 759b07d

File tree

1 file changed

+76
-0
lines changed

1 file changed

+76
-0
lines changed

README.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,79 @@ There are many cool features provided by `vue-loader`:
4242
- State-preserving hot-reloading during development.
4343

4444
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/compiler-sfc`. 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, **after** `css-loader` but **before** `style-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!source.vue?vue&type=template'
117+
118+
// <style scoped lang="scss">
119+
import 'style-loader!vue-loader/style-post-loader!css-loader!sass-loader!vue-loader!source.vue?vue&type=style&index=1&scoped&lang=scss'
120+
```

0 commit comments

Comments
 (0)