initial check-in of webpack template

Author: addyosmani

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.DS_Store
+docs/_book

README.md

@@ -0,0 +1,59 @@
+# vue-webpack-boilerplate
+
+> A full-featured Webpack setup with hot-reload, lint-on-save, unit testing & css extraction.
+
+> This template is Vue 2.0 compatible. For Vue 1.x use this command: `vue init webpack#1.0 my-project`
+
+## Documentation
+
+- [For this template](http://vuejs-templates.github.io/webpack): common questions specific to this template are answered and each part is described in greater detail
+- [For Vue 2.0](http://vuejs.org/guide/): general information about how to work with Vue, not specific to this template
+
+## Usage
+
+This is a project template for [vue-cli](https://github.com/vuejs/vue-cli). **It is recommended to use npm 3+ for a more efficient dependency tree.**
+
+``` bash
+$ npm install -g vue-cli
+$ vue init webpack my-project
+$ cd my-project
+$ npm install
+$ npm run dev
+```
+
+If port 8080 is already in use on your machine you must change the port number in `/config/index.js`. Otherwise `npm run dev` will fail.
+
+## What's Included
+
+- `npm run dev`: first-in-class development experience.
+  - Webpack + `vue-loader` for single file Vue components.
+  - State preserving hot-reload
+  - State preserving compilation error overlay
+  - Lint-on-save with ESLint
+  - Source maps
+
+- `npm run build`: Production ready build.
+  - JavaScript minified with [UglifyJS](https://github.com/mishoo/UglifyJS2).
+  - HTML minified with [html-minifier](https://github.com/kangax/html-minifier).
+  - CSS across all components extracted into a single file and minified with [cssnano](https://github.com/ben-eb/cssnano).
+  - All static assets compiled with version hashes for efficient long-term caching, and a production `index.html` is auto-generated with proper URLs to these generated assets.
+  - Use `npm run build --report`to build with bundle size analytics.
+
+- `npm run unit`: Unit tests run in PhantomJS with [Karma](http://karma-runner.github.io/0.13/index.html) + [Mocha](http://mochajs.org/) + [karma-webpack](https://github.com/webpack/karma-webpack).
+  - Supports ES2015+ in test files.
+  - Supports all webpack loaders.
+  - Easy mock injection.
+
+- `npm run e2e`: End-to-end tests with [Nightwatch](http://nightwatchjs.org/).
+  - Run tests in multiple browsers in parallel.
+  - Works with one command out of the box:
+    - Selenium and chromedriver dependencies automatically handled.
+    - Automatically spawns the Selenium server.
+
+### Fork It And Make Your Own
+
+You can fork this repo to create your own boilerplate, and use it with `vue-cli`:
+
+``` bash
+vue init username/repo my-project
+```

circle.yml

@@ -0,0 +1,7 @@
+machine:
+  node:
+    version: 6
+
+test:
+  override:
+    - bash test.sh

deploy-docs.sh

@@ -0,0 +1,8 @@
+cd docs
+rm -rf _book
+gitbook build
+cd _book
+git init
+git add -A
+git commit -m 'update book'
+git push -f [email protected]:vuejs-templates/webpack.git master:gh-pages

docs/README.md

@@ -0,0 +1,17 @@
+# Introduction
+
+This boilerplate is targeted towards large, serious projects and assumes you are somewhat familiar with Webpack and `vue-loader`. Make sure to also read [`vue-loader`'s documentation](http://vuejs.github.io/vue-loader/index.html) for common workflow recipes.
+
+If you just want to try out `vue-loader` or whip out a quick prototype, use the [webpack-simple](https://github.com/vuejs-templates/webpack-simple) template instead.
+
+## Quickstart
+
+To use this template, scaffold a project with [vue-cli](https://github.com/vuejs/vue-cli). **It is recommended to use npm 3+ for a more efficient dependency tree.**
+
+``` bash
+$ npm install -g vue-cli
+$ vue init webpack my-project
+$ cd my-project
+$ npm install
+$ npm run dev
+```

docs/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Project Structure](structure.md)
+- [Build Commands](commands.md)
+- [Linter Configuration](linter.md)
+- [Pre-Processors](pre-processors.md)
+- [Handling Static Assets](static.md)
+- [Environment Variables](env.md)
+- [Integrate with Backend Framework](backend.md)
+- [API Proxying During Development](proxy.md)
+- [Unit Testing](unit.md)
+- [End-to-end Testing](e2e.md)
+- [Prerendering for SEO](prerender.md)

docs/backend.md

@@ -0,0 +1,63 @@
+# Integrating with Backend Framework
+
+If you are building a purely-static app (one that is deployed separately from the backend API), then you probably don't even need to edit `config/index.js`. However, if you want to integrate this template with an existing backend framework, e.g. Rails/Django/Laravel, which comes with their own project structures, you can edit `config/index.js` to directly generate front-end assets into your backend project.
+
+Let's take a look at the default `config/index.js`:
+
+``` js
+var path = require('path')
+
+module.exports = {
+  build: {
+    index: path.resolve(__dirname, 'dist/index.html'),
+    assetsRoot: path.resolve(__dirname, 'dist'),
+    assetsSubDirectory: 'static',
+    assetsPublicPath: '/',
+    productionSourceMap: true
+  },
+  dev: {
+    port: 8080,
+    proxyTable: {}
+  }
+}
+```
+
+Inside the `build` section, we have the following options:
+
+### `build.index`
+
+> Must be an absolute path on your local file system.
+
+This is where the `index.html` (with injected asset URLs) will be generated.
+
+If you are using this template with a backend-framework, you can edit `index.html` accordingly and point this path to a view file rendered by your backend app, e.g. `app/views/layouts/application.html.erb` for a Rails app, or `resources/views/index.blade.php` for a Laravel app.
+
+### `build.assetsRoot`
+
+> Must be an absolute path on your local file system.
+
+This should point to the root directory that contains all the static assets for your app. For example, `public/` for both Rails/Laravel.
+
+### `build.assetsSubDirectory`
+
+Nest webpack-generated assets under this directory in `build.assetsRoot`, so that they are not mixed with other files you may have in `build.assetsRoot`. For example, if `build.assetsRoot` is `/path/to/dist`, and `build.assetsSubDirectory` is `static`, then all Webpack assets will be generated in `path/to/dist/static`.
+
+This directory will be cleaned before each build, so it should only contain assets generated by the build.
+
+Files inside `static/` will be copied into this directory as-is during build. This means if you change this prefix, all your absolute URLs referencing files in `static/` will also need to be changed. See [Handling Static Assets](static.md) for more details.
+
+### `build.assetsPublicPath`
+
+This should be the URL path where your `build.assetsRoot` will be served from over HTTP. In most cases, this will be root (`/`). Only change this if your backend framework serves static assets with a path prefix. Internally, this is passed to Webpack as `output.publicPath`.
+
+### `build.productionSourceMap`
+
+Whether to generate source maps for production build.
+
+### `dev.port`
+
+Specify the port for the dev server to listen to.
+
+### `dev.proxyTable`
+
+Define proxy rules for the dev server. See [API Proxying During Development](proxy.md) for more details.

docs/commands.md

@@ -0,0 +1,39 @@
+# Build Commands
+
+All build commands are executed via [NPM Scripts](https://docs.npmjs.com/misc/scripts).
+
+### `npm run dev`
+
+> Starts a Node.js local development server. See [API Proxying During Development](proxy.md) for more details.
+
+- Webpack + `vue-loader` for single file Vue components.
+- State preserving hot-reload
+- State preserving compilation error overlay
+- Lint-on-save with ESLint
+- Source maps
+
+### `npm run build`
+
+> Build assets for production. See [Integrating with Backend Framework](backend.md) for more details.
+
+- JavaScript minified with [UglifyJS](https://github.com/mishoo/UglifyJS2).
+- HTML minified with [html-minifier](https://github.com/kangax/html-minifier).
+- CSS across all components extracted into a single file and minified with [cssnano](https://github.com/ben-eb/cssnano).
+- All static assets compiled with version hashes for efficient long-term caching, and a production `index.html` is auto-generated with proper URLs to these generated assets.
+
+### `npm run unit`
+
+> Run unit tests in PhantomJS with [Karma](https://karma-runner.github.io/). See [Unit Testing](unit.md) for more details.
+
+- Supports ES2015+ in test files.
+- Supports all webpack loaders.
+- Easy [mock injection](http://vuejs.github.io/vue-loader/en/workflow/testing-with-mocks.html).
+
+### `npm run e2e`
+
+> Run end-to-end tests with [Nightwatch](http://nightwatchjs.org/). See [End-to-end Testing](e2e.md) for more details.
+
+- Run tests in multiple browsers in parallel.
+- Works with one command out of the box:
+  - Selenium and chromedriver dependencies automatically handled.
+  - Automatically spawns the Selenium server.

docs/e2e.md

@@ -0,0 +1,25 @@
+# End-to-end Testing
+
+This boilerplate uses [Nightwatch.js](http://nightwatchjs.org) for e2e tests. Nightwatch.js is a highly integrated e2e test runner built on top of Selenium. This boilerplate comes with Selenium server and chromedriver binaries pre-configured for you, so you don't have to mess with these yourself.
+
+Let's take a look at the files in the `test/e2e` directory:
+
+- `runner.js`
+
+  A Node.js script that starts the dev server, and then launches Nightwatch to run tests against it. This is the script that will run when you run `npm run e2e`.
+
+- `nightwatch.conf.js`
+
+  Nightwatch configuration file. See [Nightwatch's docs on configuration](http://nightwatchjs.org/guide#settings-file) for more details.
+
+- `custom-assertions/`
+
+  Custom assertions that can be used in Nightwatch tests. See [Nightwatch's docs on writing custom assertions](http://nightwatchjs.org/guide#writing-custom-assertions) for more details.
+
+- `specs/`
+
+  Your actual tests! See [Nightwatch's docs on writing tests](http://nightwatchjs.org/guide#writing-tests) and [API reference](http://nightwatchjs.org/api) for more details.
+
+### Running Tests in More Browsers
+
+To configure which browsers to run the tests in, add an entry under "test_settings" in [`test/e2e/nightwatch.conf.js`](https://github.com/vuejs-templates/webpack/blob/master/template/test/e2e/nightwatch.conf.js#L17-L39) , and also the `--env` flag in [`test/e2e/runner.js`](https://github.com/vuejs-templates/webpack/blob/master/template/test/e2e/runner.js#L15). If you wish to configure remote testing on services like SauceLabs, you can either make the Nightwatch config conditional based on environment variables, or use a separate config file altogether. Consult [Nightwatch's docs on Selenium](http://nightwatchjs.org/guide#selenium-settings) for more details.

docs/env.md

@@ -0,0 +1,51 @@
+# Environment Variables
+
+Sometimes it is practical to have different config values according to the environment that the application is running in.
+
+As an example:
+
+```js
+// config/prod.env.js
+module.exports = {
+  NODE_ENV: '"production"',
+  DEBUG_MODE: false,
+  API_KEY: '"..."' // this is shared between all environments
+}
+
+// config/dev.env.js
+module.exports = merge(prodEnv, {
+  NODE_ENV: '"development"',
+  DEBUG_MODE: true // this overrides the DEBUG_MODE value of prod.env
+})
+
+// config/test.env.js
+module.exports = merge(devEnv, {
+  NODE_ENV: '"testing"'
+})
+```
+
+> **Note:** string variables need to be wrapped into single and double quotes `'"..."'`
+
+So, the environment variables are:
+- Production
+    - NODE_ENV   = 'production',
+    - DEBUG_MODE = false,
+    - API_KEY    = '...'
+- Development
+    - NODE_ENV   = 'development',
+    - DEBUG_MODE = true,
+    - API_KEY    = '...'
+- Testing
+    - NODE_ENV   = 'testing',
+    - DEBUG_MODE = true,
+    - API_KEY    = '...'
+
+As we can see, `test.env` inherits the `dev.env` and the `dev.env` inherits the `prod.env`.
+
+### Usage
+
+It is simple to use the environment variables in your code. For example:
+
+```js
+Vue.config.debug = process.env.DEBUG_MODE
+```

docs/linter.md

@@ -0,0 +1,15 @@
+# Linter Configuration
+
+This boilerplate uses [ESLint](http://eslint.org/) as the linter, and uses the [Standard](https://github.com/feross/standard/blob/master/RULES.md) preset with some small customizations.
+
+If you are not happy with the default linting rules, you have several options:
+
+1. Overwrite individual rules in `.eslintrc.js`. For example, you can add the following rule to enforce semicolons instead of omitting them:
+
+  ``` js
+  "semi": [2, "always"]
+  ```
+
+2. Pick a different ESLint preset when generating the project, for example [eslint-config-airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb).
+
+3. Pick "none" for ESLint preset when generating the project and define your own rules. See [ESLint documentation](http://eslint.org/docs/rules/) for more details.

docs/pre-processors.md

@@ -0,0 +1,51 @@
+# Pre-Processors
+
+This boilerplate has pre-configured CSS extraction for most popular CSS pre-processors including LESS, SASS, Stylus, and PostCSS. To use a pre-processor, all you need to do is installing the appropriate webpack loader for it. For example, to use SASS:
+
+``` bash
+npm install sass-loader node-sass --save-dev
+```
+
+Note you also need to install `node-sass` because `sass-loader` depends on it as a peer dependency.
+
+### Using Pre-Processors inside Components
+
+Once installed, you can use the pre-processors inside your `*.vue` components using the `lang` attribute on `<style>` tags:
+
+``` html
+<style lang="scss">
+/* write SASS! */
+</style>
+```
+
+### A note on SASS syntax
+
+- `lang="scss"` corresponds to the CSS-superset syntax (with curly braces and semicolones).
+- `lang="sass"` corresponds to the indentation-based syntax.
+
+### PostCSS
+
+Styles in `*.vue` files are piped through PostCSS by default, so you don't need to use a specific loader for it. You can simply add PostCSS plugins you want to use in `build/webpack.base.conf.js` under the `vue` block:
+
+``` js
+// build/webpack.base.conf.js
+module.exports = {
+  // ...
+  vue: {
+    postcss: [/* your plugins */]
+  }
+}
+```
+
+See [vue-loader's related documentation](http://vuejs.github.io/vue-loader/en/features/postcss.html) for more details.
+
+### Standalone CSS Files
+
+To ensure consistent extraction and processing, it is recommended to import global, standalone style files from your root `App.vue` component, for example:
+
+``` html
+<!-- App.vue -->
+<style src="./styles/global.less" lang="less"></style>
+```
+
+Note you should probably only do this for the styles written by yourself for your application. For existing libraries e.g. Bootstrap or Semantic UI, you can place them inside `/static` and reference them directly in `index.html`. This avoids extra build time and also is better for browser caching. (See [Static Asset Handling](static.md))