Skip to content

build.md

Latest commit

 

History

History
298 lines (195 loc) · 7.26 KB

build.md

File metadata and controls

298 lines (195 loc) · 7.26 KB

vue build

vue build command gives you a zero-configuration development setup, install once and build everywhere.

Features

  • Not a boilerplate: run a single command to develop your app
  • Out of the box: ES2015, single-file component with hot reloading and custom CSS preprocessors
  • Customizable: populate a ~/.vue/webpack.config.js for custom webpack config
  • Single-file component mode: simply run vue build Component.vue and test it out in the browser!

Get started

Make sure that you've installed vue-cli with npm >= 3 or yarn >= 0.7.

Populate an app entry ./index.js in your project:

import Vue from 'vue'

new Vue({
  el: '#app',
  render: h => h('h2', 'hello world')
})

And then run vue build index.js and go to http://localhost:4000

To build for production (minimized and optimized):

$ vue build index.js --prod

If you want to directly test a component without manually create a Vue instance for it, try:

$ vue build Component.vue
How does this work?
When the input file ends with `.vue` extension, we use a [default app entry](/lib/default-entry.es6) to load the given component, otherwise we treat it as a normal webpack entry. For jsx component which ends with `.js` extension, you can enable this behavior manually by adding `--mount`.

To distribute component:

$ vue build Component.vue --prod --lib

This will create an optimized bundle in UMD format, and the name of exported library is set to Component, you can use --lib [CustomLibraryName] to customize it.

Note that in some cases you may use externals to exclude some modules from your bundle.

Watch mode:

$ vue build index.js --watch

It's similar to development mode but does not add hot-reloading support and uses a real file system.

For more CLI usages:

$ vue build -h

Configuration files

By default, we use ~/.vue/config.js and ~/.vue/webpack.config.js if they exist.

To use a custom config file, add --config [file]

To use a custom webpack config file, add --webpack [file]

config.js

You can define CLI options in this file.

entry

Type: string Array Object

It's the first argument of vue build command, eg: vue build entry.js. You can set it here to omit it in CLI arguments.

The single-component mode (--mount) will not work if you set entry to an Array or Object.

  • Array: Override webpackConfig.entry.client
  • Object: Override webpackConfig.entry
  • string: Added to webpackConfig.entry.client or used as webpackConfig.resolve.alias['your-tasteful-component'] in single-component mode.

port

Type: number
Default: 4000

Port of dev server.

webpack

Type: function string object

function

webpack(webpackConfig, options, webpack)

  • webpackConfig: current webpack config
  • options: CLI options (assigned with config.js)
  • webpack: The webpack module

Return a new webpack config.

string

Used as the path to webpack config file, eg: --webpack webpack.config.js

object

Directly use as webpack config.

Note that we use webpack-merge to merge your webpack config with default webpack config.

autoprefixer

Type: object

Autoprefixer options, default value:

{
  browsers: ['ie > 8', 'last 5 versions']
}

postcss

Type: Object Array Function

PostCSS options, if it's an Array or Function, the default value will be override:

{
  plugins: [
    require('autoprefixer')(options.autoprefixer)
  ]
}

babel

Type: Object

Babel options. You can set babel.babelrc to false to disable using .babelrc.

html

Type: Object Array boolean

html-webpack-plugin options, use this option to customize index.html output, default value:

{
  title: 'Vue App',
  template: path.join(__dirname, '../lib/template.html')
}

Check out the default template file we use. To disable generating html file, you can set html to false.

filename

Set custom filename for js css static files:

{
  filename: {
    js: 'index.js',
    css: 'style.css',
    static: 'static/[name].[ext]'  
  }
}

disableCompress

Type: boolean

In production mode, all generated files will be compressed and produce sourcemaps file. You can use --disableCompress to disable this behavior.

hmrEntries

Type: Array
Default: ['client']

Add webpack-hot-middleware HMR client to specific webpack entries. By default your app is loaded in client entry, so we insert it here.

proxy

Type: string, Object

To tell the development server to serve any /api/* request to your API server in development, use the proxy options:

module.exports = {
  proxy: 'http://localhost:8080/api'
}

This way, when you fetch /api/todos in your Vue app, the development server will proxy your request to http://localhost:8080/api/todos.

We use http-proxy-middleware under the hood, so the proxy option can also be an object:

module.exports = {
  proxy: {
    '/api/foo': 'http://localhost:8080/api',
    '/api/fake-data': {
      target: 'http://jsonplaceholder.typicode.com',
      changeOrigin: true,
      pathRewrite: {
        '^/api/fake-data': ''
      }
    }
  }
}

Keep in mind that proxy only has effect in development.

setup

Type: function

Perform some custom logic to development server:

module.exports = {
  setup(app) {
    app.get('/api', (req, res) => {
      res.end('This is the API')
    })
  }
}

run(webpackConfig, options)

Type: function

You can use a custom run function to perform your own build process instead of the default one. For example, run karma with the processed webpack config:

const Server = require('karma').Server

module.exports = {
  run(webpackConfig) {
    const server = new Server({
      webpack: webpackConfig,
      // other karma options...
    }, exitCode => {
      console.log('Karma has exited with ' + exitCode)
      process.exit(exitCode)
    })
    server.start()
  }
}

webpack.config.js

All the webpack options are available here.

Recipes

Custom CSS preprocessors

CSS preprocessors (and CSS extraction) work out of the box, install relevant loaders and you're all set! For example, add sass support:

$ npm i -D node-sass sass-loader

Since all CSS will be piped through postcss-loader, autoprefixer and postcss options will always work no matter what CSS preprocessors you're using.

Custom babel config

By default we only use a single babel preset: babel-preset-vue-app which includes following features:

  • ES2015/2016/2017 and Stage-2 features
  • Transform async/await and generator
  • Transform Vue JSX

You can set babel option in config file or populate a .babelrc in project root directory to override it.

Copy static files

Everything in ./static folder will be copied to dist folder, for example: static/favicon.ico will be copied to dist/favicon.ico.