Skip to content

Commit 9ca77cd

Browse files
committed
docs: static assets and build targets
1 parent 8b79644 commit 9ca77cd

File tree

3 files changed

+175
-4
lines changed

3 files changed

+175
-4
lines changed

docs/README.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,6 @@ See [CLI Service docs](./cli-service.md) for all available commands.
5757

5858
The file `public/index.html` is a template that will be processed with [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin). During build, asset links will be injected automatically. In addition, Vue CLI also automatically injects resource hints (`preload/prefetch`), manifest/icon links (when PWA plugin is used) and inlines the webpack runtime / chunk manifest for optimal performance.
5959

60-
You can edit the file to add your own tags, but note one thing: you need to prefix links to assets with `<%= webpackConfig.output.publicPath %>` in case you are not deploying your app at the root of a domain.
61-
6260
### Static Assets Handling
6361

6462
Static assets can be handled in two different ways:

docs/assets.md

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,78 @@
1-
## [TODO] Static Asset Handling
1+
## Static Asset Handling
2+
3+
- [Relative Path Imports](#relative-path-imports)
4+
- [URL Transform Rules](#url-transform-rules)
5+
- [The `public` Folder](#the-public-folder)
6+
- [When to use the `public` folder](#when-to-use-the-public-folder)
7+
8+
### Relative Path Imports
9+
10+
When you reference a static asset using relative path inside JavaScript, CSS or `*.vue` files, the asset will be included into webpack's dependency graph. During this compilation process, all asset URLs such as `<img src="...">`, `background: url(...)` and CSS `@import` are **resolved as module dependencies**.
11+
12+
For example, `url(./image.png)` will be translated into `require('./image.png')`, and
13+
14+
``` html
15+
<img src="../image.png">
16+
```
17+
18+
will be compiled into:
19+
20+
``` js
21+
createElement('img', { attrs: { src: require('../image.png') }})
22+
```
23+
24+
Internally, we use `file-loader` to determine the final file location with version hashes and correct public base paths, and use `url-loader` to conditional inline assets that are smaller than 10kb, reducing the amount of HTTP requests.
25+
26+
#### URL Transform Rules
27+
28+
- If the URL is an absolute path (e.g. `/images/foo.png`), it will be preserved as-is.
29+
30+
- If the URL starts with `.`, it's interpreted as a relative module request and resolved based on the folder structure on your file system.
31+
32+
- If the URL starts with `~`, anything after it is interpreted as a module request. This means you can even reference assets inside node modules:
33+
34+
``` html
35+
<img src="~/some-npm-package/foo.png">
36+
```
37+
38+
- If the URL starts with `@`, it's also interpreted as a module request. This is useful because Vue CLI by default aliases `@` to `<projectRoot>/src`.
39+
40+
### The `public` Folder
41+
42+
Any static assets placed in the `public` folder will simply be copied and not go through webpack. You need to reference to them using absolute paths.
43+
44+
Note we recommended importing assets as part of your module dependency graph so that they will go through webpack with the following benefits:
45+
46+
- Scripts and stylesheets get minified and bundled together to avoid extra network requests.
47+
- Missing files cause compilation errors instead of 404 errors for your users.
48+
- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
49+
50+
The `public` directory is provided as an **escape hatch**, and when you reference it via absolute path, you need to take into account where your app will be deployed. If your app is not deployed at the root of a domain, you will need to prefix your URLs with the base path:
51+
52+
- In `public/index.html`, you need to prefix the link with `<%= webpackConfig.output.publicPath %>`:
53+
54+
``` html
55+
<link rel="shortcut icon" href="<%= webpackConfig.output.publicPath %>favicon.ico">
56+
```
57+
58+
- In templates, you will need to first pass the base URL to your component:
59+
60+
``` js
61+
data () {
62+
return {
63+
baseUrl: process.env.BASE_URL
64+
}
65+
}
66+
```
67+
68+
Then:
69+
70+
``` html
71+
<img :src="`${baseUrl}my-image.png`">
72+
```
73+
74+
#### When to use the `public` folder
75+
76+
- You need a file with a specific name in the build output.
77+
- You have thousands of images and need to dynamically reference their paths.
78+
- Some library may be incompatible with Webpack and you have no other option but to include it as a `<script>` tag.

docs/build-targets.md

Lines changed: 97 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,103 @@
1-
## [TODO] Build Targets
1+
## Build Targets
22

33
### App
44

5+
App mode is the default mode. In this mode:
6+
7+
- `index.html` with asset and resource hints injection
8+
- vendor libraries split into a separate chunk for better caching
9+
- static assets under 10kb are inlined into JavaScript
10+
- static assets in `public` are copied into output directory
11+
512
### Library
613

14+
You can build a single entry as a library using
15+
16+
```
17+
vue-cli-service build --target lib --name myLib [entry]
18+
```
19+
20+
The entry can be either a `.js` or a `.vue` file. If no entry is specified, `src/App.vue` will be used.
21+
22+
A lib build outputs:
23+
24+
- `dist/myLib.common.js`
25+
26+
A CommonJS bundle for consuming via bundlers (unfortunately, webpack currently does not support ES modules output format for bundles yet)
27+
28+
- `dist/myLib.umd.js`
29+
30+
A UMD bundle for consuming directly in browsers or with AMD loaders
31+
32+
- `dist/myLib.umd.min.js`
33+
34+
Minified version of the UMD build.
35+
36+
- `dist/myLib.css`
37+
38+
Extracted CSS file (can be forced into inlined by setting `css: { extract: false }` in `vue.config.js`)
39+
740
### Web Component
41+
42+
> [Compatibility](https://github.com/vuejs/vue-web-component-wrapper#compatibility)
43+
44+
You can build a single entry as a library using
45+
46+
```
47+
vue-cli-service build --target wc --name my-element [entry]
48+
```
49+
50+
This will produce a single JavaScript file (and its minified version) with everything inlined. The script, when included on a page, registers the `<my-element>` custom element, which wraps the target Vue component using `@vue/web-component-wrapper`. The wrapper automatically proxies properties, attributes, events and slots. See the [docs for `@vue/web-component-wrapper`](https://github.com/vuejs/vue-web-component-wrapper) for more details.
51+
52+
Note the bundle relies on `Vue` being globally available on the page.
53+
54+
This mode allows consumers of your component to use the Vue component as a normal DOM element:
55+
56+
``` html
57+
<script src="https://unpkg.com/vue"></script>
58+
<script src="path/to/my-element.js"></script>
59+
60+
<!-- use in plain HTML, or in any other framework -->
61+
<my-element></my-element>
62+
```
63+
64+
#### Bundle that Registers Multiple Web Components
65+
66+
When building a web component bundle, you can also target multiple components by using a glob as entry:
67+
68+
```
69+
vue-cli-service build --target wc --name foo 'src/components/*.vue'
70+
```
71+
72+
When building multiple web components, `--name` will be used as the prefix and the custom element name will be inferred from the component filename. For example, with `--name foo` and a component named `HelloWorld.vue`, the resulting custom element will be registered as `<foo-hello-world>`.
73+
74+
### Async Web Component
75+
76+
> [Compatibility](https://github.com/vuejs/vue-web-component-wrapper#compatibility)
77+
78+
When targeting multiple web components, the bundle may become quite large, and the user may only use a few of the components your bundle registers. The async web component mode produces a code-split bundle with a small entry file that provides the shared runtime between all the components, and registers all the custom elements upfront. The actual implementation of a component is then fetched on-demand only when an instance of the corresponding custom element is used on the page:
79+
80+
```
81+
vue-cli-service build --target wc-async --name foo 'src/components/*.vue'
82+
```
83+
84+
```
85+
File Size Gzipped
86+
87+
dist/foo.0.min.js 12.80 kb 8.09 kb
88+
dist/foo.min.js 7.45 kb 3.17 kb
89+
dist/foo.1.min.js 2.91 kb 1.02 kb
90+
dist/foo.js 22.51 kb 6.67 kb
91+
dist/foo.0.js 17.27 kb 8.83 kb
92+
dist/foo.1.js 5.24 kb 1.64 kb
93+
```
94+
95+
Now on the page, the user only needs to include Vue and the entry file:
96+
97+
``` html
98+
<script src="https://unpkg.com/vue"></script>
99+
<script src="path/to/foo.min.js"></script>
100+
101+
<!-- foo-one's implementation chunk is auto fetched when it's used -->
102+
<foo-one></foo-one>
103+
```

0 commit comments

Comments
 (0)