When you run vue-cli-service build you can specify a different build target with the --target option. It allows you to take the same source code and generate different builds for different use cases.
application
Application mode is the default mode. In this pattern:
- index.html will have injected resources and resource hints
- Third-party libraries will be divided into a separate package for better caching
- Static resources smaller than 4kb will be inlined in JavaScript
- Static resources in public will be copied to the output directory
library
Reminder about IE Compatibility
In the library mode, the publicPath of the project is dynamically set according to the loading path of the main file (to support dynamic resource loading capabilities). But this feature uses document.currentScript, and IE browser does not support this feature. So if the website needs to support IE, it is recommended to introduce current-script-polyfill on the page before using the library .
Note the dependency on Vue
In library mode, Vue is external. This means that there will be no Vue in the package, even if you import Vue in your code. If the library will be used through a bundler, it will attempt to load Vue through the bundler as a dependency; otherwise it will fall back to a global Vue variable.
To avoid this behavior, you can add the --inline-vue flag to the build command.
vue-cli-service build --target lib --inline-vue
You can build a single entry as a library with the following command:
vue-cli-service build --target lib --name myLib [entry]
File Size Gzipped
dist/myLib.umd.min.js 13.28 kb 8.42 kb
dist/myLib.umd.js 20.95 kb 10.22 kb
dist/myLib.common.js 20.57 kb 10.09 kb
dist/myLib.css 0.33 kb 0.23 kb
This entry can be a .js or a .vue file. If no entry is specified, src/App.vue will be used.
Building a library will output:
- dist/myLib.common.js: a CommonJS package for bundlers (unfortunately, webpack does not yet support the ES modules output format)
- dist/myLib.umd.js: A UMD package directly for browser or AMD loader
- dist/myLib.umd.min.js: minified UMD build
- dist/myLib.css: The extracted CSS file (can be forced to be inlined by setting css: { extract: false } in vue.config.js )
warn
If you're developing a library or multi-project repository (monorepo), be aware that importing CSS has side effects. Make sure to remove "sideEffects": false in package.json, otherwise the CSS block will be discarded by webpack during production build.
Vue vs. JS/TS entry file
When using a .vue file as an entry point, your library directly exposes the Vue component itself, since components are always exported by default.
However, when you use a .js or .ts file as an entry point, it may contain named exports, so the library is exposed as a module. That means your library must be accessed via window.yourLib.default in UMD builds, or const myLib = require('mylib').default in CommonJS builds. If you don't have any named exports and want to expose the default export directly, you can use the following webpack configuration in vue.config.js :
module.exports = {
configureWebpack: {
output: {
libraryExport: 'default'
}
}
}
Web Components component
Compatibility Tips
Web Components mode does not support IE11 and lower versions. more details
Note the dependency on Vue
In the Web Components pattern, Vue is external. This means that there will be no Vue in the package, even if you import Vue in your code. The package here will assume that there is already a global variable Vue available in the page.
You can build a single entry as a Web Components component with the following command:
vue-cli-service build --target wc --name my-element [entry]
Note that the entry here should be a *.vue file. Vue CLI will automatically wrap and register this component as a Web Components component, no need to register it in main.js. You can also use main.js alone as a demo app during development.
The build will produce a single JavaScript file (and its minified version) with everything inlined. When this script is imported into a web page, it will register a custom component <my-element> that uses @vue/web-component-wrapper to wrap the target Vue component. This wrapper automatically proxies properties, attributes, events and slots. Please refer to the documentation of @vue/web-component-wrapper for more details.
Note that this package depends on Vue being globally available on the page.
This pattern allows consumers of your component to consume the Vue component as a normal DOM element:
<script src="https://unpkg.com/vue" rel="external nofollow" rel="external nofollow" ></script>
<script src="path/to/my-element.js"></script>
<!-- 可在普通 HTML 中或者其它任何框架中使用 -->
<my-element></my-element>
A package that registers multiple Web Components components
When you build a Web Components package, you can also use a glob expression as an entry to specify multiple component targets:
vue-cli-service build --target wc --name foo 'src/components/*.vue'
When you build multiple web components, --name will be used to set the prefix, and the name of the custom element will be deduced from the component's filename. For example, a component named HelloWorld.vue with --name foo will generate a custom element named <foo-hello-world>.
Asynchronous Web Components components
When targeting multiple Web Components, the bundle can become very large, and users may only want to use a subset of the components registered with your bundle. At this time, the asynchronous Web Components mode will generate a code-split package with a runtime shared by all components and pre-register all custom component small entry files. The actual implementation of a component will only be obtained on demand when a corresponding instance of the custom element is used in the page:
vue-cli-service build --target wc-async --name foo 'src/components/*.vue'
File Size Gzipped
dist/foo.0.min.js 12.80 kb 8.09 kb
dist/foo.min.js 7.45 kb 3.17 kb
dist/foo.1.min.js 2.91 kb 1.02 kb
dist/foo.js 22.51 kb 6.67 kb
dist/foo.0.js 17.27 kb 8.83 kb
dist/foo.1.js 5.24 kb 1.64 kb
Now users only need to introduce Vue and this entry file on this page:
<script src="https://unpkg.com/vue" rel="external nofollow" rel="external nofollow" ></script>
<script src="path/to/foo.min.js"></script>
<!-- foo-one 的实现的 chunk 会在用到的时候自动获取 -->
<foo-one></foo-one>