You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you are not interested in manually setting up webpack, it is recommended to scaffold a project with [Vue CLI](https://github.com/vuejs/vue-cli) instead. Projects created by Vue CLI is pre-configured with most of the common development needs and works out of the box.
6
+
7
+
Follow this guide if the built-in configuration of Vue CLI does not suit your needs, or you'd rather create your own webpack config from scratch.
8
+
9
+
## Manual Configuration
10
+
11
+
Vue Loader's configuration is a bit different form other loaders. In addition to a rule that applies `vue-loader` to any files with extension `.vue`, make sure to add Vue Loader's plugin to your webpack config:
12
+
13
+
```js
14
+
// webpack.config.js
15
+
const { VueLoaderPlugin } =require('vue-loader')
16
+
17
+
module.exports= {
18
+
module: {
19
+
rules: [
20
+
// ... other rules
21
+
{
22
+
test:/\.vue$/,
23
+
loader:'vue-loader'
24
+
}
25
+
]
26
+
},
27
+
plugins: [
28
+
// make sure to include the plugin!
29
+
newVueLoaderPlugin()
30
+
]
31
+
}
32
+
```
33
+
34
+
**The plugin is required.** It is responsible for cloning any other rules you have defined and applying them to the corresponding language blocks in `.vue` files. For example, if you have a rule matching `/\.js$/`, it will be applied to `<script>` blocks in `.vue` files.
35
+
36
+
A more complete example webpack config will look like this:
Copy file name to clipboardExpand all lines: docs/guide/asset-url.md
+20-10
Original file line number
Diff line number
Diff line change
@@ -1,20 +1,30 @@
1
1
# Asset URL Handling
2
2
3
-
By default, `vue-loader` automatically processes your style and template files with [css-loader](https://github.com/webpack/css-loader) and the Vue template compiler. In this compilation process, all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
3
+
When Vue Loader compiles the `<template>` blocks in SFCs, it also converts any encountered asset URLs into **webpack module requests**.
4
4
5
-
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
src:require('../image.png') // this is now a module request
17
+
}
18
+
})
15
19
```
16
20
17
-
### Transform Rules
21
+
By default the following tag/attribute combinations are transformed, and can be configured using the [transformAssetUrls](../config.md#transformasseturls) option.
22
+
23
+
In addition, if you have configured to use [css-loader](https://github.com/webpack-contrib/css-loader) for the `<style>` blocks, asset URLs in your CSS will also be processed in a similar fashion.
24
+
25
+
## Transform Rules
26
+
27
+
Asset URL transforms adhere to the following rules:
18
28
19
29
- If the URL is an absolute path (e.g. `/images/foo.png`), it will be preserved as-is.
-(13.7.0+) If the URL starts with `@`, it's also interpreted as a module request. This is useful if your webpack config has an alias for `@`, which by default points to `/src` in any project created by `vue-cli`.
39
+
- If the URL starts with `@`, it's also interpreted as a module request. This is useful if your webpack config has an alias for `@`, which by default points to `/src` in any project created by `vue-cli`.
30
40
31
-
###Related Loaders
41
+
## Related Loaders
32
42
33
-
Because `.png`is not a JavaScript file, you will need to configure webpack to use [file-loader](https://github.com/webpack/file-loader) or [url-loader](https://github.com/webpack/url-loader) to handle them. The project scaffolded with `vue-cli`has also configured this for you.
43
+
Because extensions like `.png`are not JavaScript modules, you will need to configure webpack to use [file-loader](https://github.com/webpack/file-loader) or [url-loader](https://github.com/webpack/url-loader) to properly handle them. Projects created with Vue CLI has this pre-configured.
34
44
35
-
###Why
45
+
## Why
36
46
37
-
The benefits of all this are:
47
+
The benefits of asset URL transforms are:
38
48
39
49
1.`file-loader` allows you to designate where to copy and place the asset file, and how to name it using version hashes for better caching. Moreover, this also means **you can just place images next to your `*.vue` files and use relative paths based on the folder structure instead of worrying about deployment URLs**. With proper config, webpack will auto-rewrite the file paths into correct URLs in the bundled output.
[CSS Modules](https://github.com/css-modules/css-modules) is a popular system for modularizing and composing CSS. `vue-loader` provides first-class integration with CSS Modules as an alternative for simulated scoped CSS.
6
4
7
-
###Usage
5
+
## Usage
8
6
9
-
Just add the `module` attribute to your `<style>`:
7
+
First, CSS Modules must be enabled by passing `modules: true`to `css-loader`:
10
8
11
-
```html
9
+
```js
10
+
// webpack.config.js
11
+
{
12
+
module: {
13
+
rules: [
14
+
// ... other rules omitted
15
+
{
16
+
test:/\.css$/,
17
+
use: [
18
+
'vue-style-loader',
19
+
{
20
+
loader:'css-loader',
21
+
options: {
22
+
// enable CSS Modules
23
+
modules:true,
24
+
// customize generated class names
25
+
localIdentName:'[local]_[hash:base64:8]'
26
+
}
27
+
}
28
+
]
29
+
}
30
+
]
31
+
}
32
+
}
33
+
```
34
+
35
+
Then, add the `module` attribute to your `<style>`:
36
+
37
+
```vue
12
38
<style module>
13
39
.red {
14
40
color: red;
@@ -19,9 +45,9 @@ Just add the `module` attribute to your `<style>`:
19
45
</style>
20
46
```
21
47
22
-
This will turn on CSS Modules mode for `css-loader`, and the resulting class identifier object will be injected into the component as a computed property with the name `$style`. You can use it in your templates with a dynamic class binding:
48
+
The `module` attribute instructs Vue Loader to inject the CSS modules locals object into the component as a computed property with the name `$style`. You can then use it in your templates with a dynamic class binding:
23
49
24
-
```html
50
+
```vue
25
51
<template>
26
52
<p :class="$style.red">
27
53
This should be red
@@ -31,7 +57,7 @@ This will turn on CSS Modules mode for `css-loader`, and the resulting class ide
31
57
32
58
Since it's a computed property, it also works with the object/array syntax of `:class`:
33
59
34
-
```html
60
+
```vue
35
61
<template>
36
62
<div>
37
63
<p :class="{ [$style.red]: isRed }">
@@ -46,12 +72,12 @@ Since it's a computed property, it also works with the object/array syntax of `:
46
72
47
73
And you can also access it from JavaScript:
48
74
49
-
```html
75
+
```vue
50
76
<script>
51
77
export default {
52
78
created () {
53
79
console.log(this.$style.red)
54
-
// -> "_1VyoJ-uZOjlOxP7jWUy19_0"
80
+
// -> "red_1VyoJ-uZ"
55
81
// an identifier generated based on filename and className.
56
82
}
57
83
}
@@ -60,47 +86,69 @@ export default {
60
86
61
87
Refer to the [CSS Modules spec](https://github.com/css-modules/css-modules) for mode details such as [global exceptions](https://github.com/css-modules/css-modules#exceptions) and [composition](https://github.com/css-modules/css-modules#composition).
62
88
63
-
### Custom Inject Name
64
-
65
-
You can have more than one `<style>` tags in a single `*.vue` component. To avoid injected styles to overwrite each other, you can customize the name of the injected computed property by giving the `module` attribute a value:
66
-
67
-
```html
68
-
<stylemodule="a">
69
-
/* identifiers injected as a */
70
-
</style>
71
-
72
-
<stylemodule="b">
73
-
/* identifiers injected as b */
74
-
</style>
75
-
```
89
+
## Opt-in Usage
76
90
77
-
### Configuring `css-loader` Query
78
-
79
-
CSS Modules are processed via [css-loader](https://github.com/webpack/css-loader). With `<style module>`, the default query used for `css-loader` is:
91
+
If you only want to use CSS Modules in some of your Vue components, you can use a `oneOf` rule and check for the `module` string in resourceQuery:
80
92
81
93
```js
94
+
// webpack.config.js -> module.rules
82
95
{
83
-
modules:true,
84
-
importLoaders:1,
85
-
localIdentName:'[hash:base64]'
96
+
test:/\.css$/,
97
+
oneOf: [
98
+
// this matches <style module>
99
+
{
100
+
resourceQuery:/module/,
101
+
use: [
102
+
'vue-style-loader',
103
+
{
104
+
loader:'css-loader',
105
+
options: {
106
+
modules:true,
107
+
localIdentName:'[local]_[hash:base64:5]'
108
+
}
109
+
}
110
+
]
111
+
},
112
+
// this matches plain <style> or <style scoped>
113
+
{
114
+
use: [
115
+
'vue-style-loader',
116
+
'css-loader'
117
+
]
118
+
}
119
+
]
86
120
}
87
121
```
88
122
89
-
You can use vue-loader's `cssModules` option to provide additional query options to `css-loader`:
123
+
## Using with Pre-Processors
124
+
125
+
CSS Modules can be used along with other pre-processors:
You can have more than one `<style>` tags in a single `*.vue` component. To avoid injected styles to overwrite each other, you can customize the name of the injected computed property by giving the `module` attribute a value:
0 commit comments