vbuild: 为 Vue.js 优化的开发工具 (基于 Webpack)

Badges

tl;dr

vbuild whatever.js --dev
# it just works

Develop Vue apps with no build configuration until you need.

• Install
• How to use
• Config file
  • Shorthand
  • Arguments
    • options
    • req
  • Babel
  • PostCSS
    • Custom CSS preprocessors
    • CSS modules
  • Webpack entry
  • Hot reloading
  • Code splitting
  • Webpack
  • Custom HTML output
  • Custom output filename
  • Extracting CSS
  • Define constants at compile time
  • Load env variables
  • Proxy API request
  • Dev server
    • port
    • host
  • Custom server logic
  • Custom build process
• JavaScript API
• Recipes
• Limitations
• FAQ
• Contributing
• Author

Install

It works with both Yarn(>=0.17) and npm(>=3):

yarn global add vbuild
# You can also install it locally
# yarn add vbuild --dev

How to use

vbuild init <folder>

Or manually, populate an entry file, let's say index.js:

import Vue from 'vue'

new Vue({
  el: '#app',
  render: h => <h1>Hello World!</h1>
})

Run app in dev mode:

vbuild index.js --dev

So far we get:

• Automatic transpilation and bundling (with webpack and babel/postcss)
• Hot code reloading
• Static file in ./static/ will be copied to ./dist/

To see how simple it is, check out our official website which is built with vbuild itself.

Build app in production mode (default mode):

vbuild index.js

⬆ back to top

Config file

All CLI options and advanced options can be set here:

module.exports = (options, req) => ({
  port: 5000
  // Other options
})

// Note that you can directly export an object too:
// module.exports = {port: 5000}

To use it, you can add --config [path] in CLI arguments. If no path was speified, it defaults to vbuild.config.js.

⬆ back to top

Shorthand

To set different config for different mode, you may use options.dev like:

module.exports = options => ({
  webpack(cfg) {
    if (options.dev) {}
    else {}
    return cfg
  }
})

To simplify this, we provide a shorthand to do this:

module.exports = {
  production: {}, // used in `!options.dev`
  development: {} // used in `options.dev`
}

The production or development config will be assigned into base config using Object.assign.

⬆ back to top

Arguments

options

CLI options.

⬆ back to top

req

The require function but context directory is the path to node_modules/vbuild/lib, which means you can use it to load vbuild's dependencies, like webpack.

⬆ back to top

Babel

JS files and script tags in single-file components are transpiled by Babel. We only use one preset by default: babel-preset-vue-app.

You can provide custom babel config by setting babel in config file or using .babelrc or setting babel field in package.json.

If you want to use custom babel config file, please set babel in config file to undefined first.

⬆ back to top

PostCSS

Standalone .css files and style tags in single-file components are transpiled by PostCSS, the only plugin we use by default is autoprefixer, and you can use autoprefixer option in config file to adjust it, here's the config with default value:

module.exports = {
  autoprefixer: {
    browsers: ['ie > 8', 'last 4 versions']
  }
}

You can also set postcss option in config file, when it's an Array or Object, we will prepend autoprefixer plugin to it. You can set autoprefixer: false to disable this though.

If you want to use PostCSS config file like postcss.config.js or whatever postcss-load-config supports, please set postcss option in config file to undefined first.

Custom CSS preprocessors

Supported preprocessors: sass scss stylus less, the workflow of CSS is custom css preprocessor -> postcss-loader -> css-loader.

To use a custom CSS preprocessor, you can directly install relevant loader and dependency. For example, to use scss:

yarn add node-sass sass-loader --dev

CSS modules

To use CSS modules in single-file component, you can set module attribute in <style></style> tag.

To use CSS modules in standalone css files, you can set cssModules to true in config file.

⬆ back to top

Webpack entry

Type: string Array Object

You can set webpack entry from CLI option or entry property in config file. If it's an array or string, we add it into webpackConfig.entry.client entry, otherwise it will totally override webpackConfig.entry

⬆ back to top

Hot reloading

By default we add HMR client to client entry, you can change it by:

module.exports = {
  hmrEntry: ['other-name']
}

⬆ back to top

Code splitting

We enabled code splitting for vendor code and app code by default in production mode, you can set vendor option to false to disable it. And by default all required modules in node_modules will be split.

⬆ back to top

Webpack

Mutate webpack config as you wish:

module.exports = options => ({
  webpack(webpackConfig) {
    if (options.dev) {
      // Apply some changes to webpackConfig
    }
    return webpackConfig
  }
})

The value of webpack could also be a plain object, this way it will be merged into default webpack config using webpack-merge.

⬆ back to top

Custom HTML output

Type: Object Array boolean

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

module.exports = {
  html: {
    title: 'VBuild',
    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.

⬆ back to top

Custom output filename

Set custom filename for js css static files:

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

⬆ back to top

Extracting CSS

The extract option is true by default in production mode, however you can also set it manually to overrde:

module.exports = {
  // always disable extracting css
  extract: false
}

Define constants at compile time

define is a short-hand to add webpack's DefinePlugin for settings global constants which can be configured at compile time.

module.exports = options => ({
  define: {
    __DEV__: JSON.stringify(options.dev)
  }
})

Then use it in your app code:

if (__DEV__) {
  // perform something only in development mode a.k.a `--dev`
}

The default constants we add is process.env.NODE_ENV. The variables you defined here are only available in app code.

⬆ back to top

Load env variables

Your project can consume variables declared in your environment as if they were declared locally in your JS files. By default you will have NODE_ENV defined.

There're three way to define env variables:

• CLI options --env.VARIABLE_NAME xxx
• env option in config file
• .env file via dotenv

You can use them in index.html and app code:

# .env file
VUE_APP_DESCRIPTION=my awesome project

In template html file which uses ejs template, you can write:

<meta name="description" content="!!VUE_APP_DESCRIPTION!!" />

In app code you need to write full reference of the variable:

const key = process.env.VUE_APP_KEY

To totally disable this, you can set env to false.

⬆ back to top

Proxy API request

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.

⬆ back to top

Dev server

port

Type: number
Default: 4000

Port of dev server.

host

Type: string
Default: localhost

Host of dev server.

⬆ back to top

Custom server logic

Perform some custom logic to development server:

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

⬆ back to top

Custom build process

Insead of letting vbuild run webpack as the build process, you can perform a custom one by using run function in config file:

// For example, run tests with Karma
const Server = require('karma').Server

module.exports = {
  run(webpackConfig) {
    const server = new Server({
      webpack: webpackConfig,
      // ...Other karma options
    })
    server.start()
  }
}

⬆ back to top

JavaScript API

You can use vbuild as a Node.js module:

const vbuild = require('vbuild')

const res = vbuild(cliOptions)
//=> console.log(res)
{
  webpackConfig, // final webpack config
  options, // final options
  compiler, // webpack compiler instance
  watcher, // in watch mode, webpack watcher
  server, // in dev mode, an instance of `http.Server` without calling `.listen`
  devMiddleware // in dev mode, the webpack-dev-middleware instance
}

// error catch
try {
  vbuild(options)
} catch (err) {
  if (err.name === 'AppError') {
    // error occurs in starting the compilation
  } else {
    // other unknown error
  }
}

⬆ back to top

Recipes

• Minimize and sourcemaps
• Bundle in CommonJS or UMD format
• Progressive web app
• Electron app
• ESLint
• Deployment
• Analyze bundle size
• Troubleshooting

⬆ back to top

Limitations

• Server-side rendering: you can generate server bundle though
• Eject webpack config: here's an on-going issue

Feel free to request new features.

FAQ

⬆ back to top

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Author

vbuild © EGOIST, Released under the MIT License.
Authored and maintained by egoist with help from contributors ( list).

egoistian.com · GitHub @egoist · Twitter @rem_rin_rin