You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-91
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,9 @@
2
2
3
3
> A full-featured Webpack setup with hot-reload, lint-on-save, unit testing & css extraction.
4
4
5
-
### Before You Start...
5
+
##Documentation
6
6
7
-
This boilerplate is targeted towards large, serious projects and contains a lot of moving pieces. 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.
7
+
Common topics are discussed in the [docs](http://vuejs-templates.github.io/webpack). Make sure to read it!
8
8
9
9
## Usage
10
10
@@ -18,36 +18,6 @@ $ npm install
18
18
$ npm run dev
19
19
```
20
20
21
-
## Folder Structure
22
-
23
-
```bash
24
-
.
25
-
├── build
26
-
│ ├── dev-server.js # development server script
27
-
│ ├── webpack.base.conf.js # shared base webpack config
28
-
│ ├── webpack.dev.conf.js # development webpack config
29
-
│ ├── webpack.prod.conf.js # production webpack config
30
-
│ └── ...
31
-
├── src
32
-
│ ├── main.js # app entry file
33
-
│ ├── App.vue # main app component
34
-
│ ├── components # ui components
35
-
│ │ └── ...
36
-
│ └── assets # module assets (processed by webpack)
37
-
│ └── ...
38
-
├── static # pure static assets (directly copied)
39
-
├── dist # built files ready for deploy
40
-
├── test
41
-
│ └── unit # unit tests
42
-
│ └── ...
43
-
│ └── e2e # e2e tests
44
-
│ └── ...
45
-
├── .babelrc # babel config
46
-
├── .eslintrc.js # eslint config
47
-
├── index.html # main html file
48
-
└── package.json # build scripts and dependencies
49
-
```
50
-
51
21
## What's Included
52
22
53
23
-`npm run dev`: first-in-class development experience.
@@ -64,7 +34,7 @@ $ npm run dev
64
34
- 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.
65
35
- Also see [deployment notes](#how-do-i-deploy-built-assets-with-my-backend-framework).
66
36
67
-
-`npm run unit`: Unit tests run in PhantomJS with [Karma](http://karma-runner.github.io/0.13/index.html) + [Jasmine](http://jasmine.github.io/) + [karma-webpack](https://github.com/webpack/karma-webpack).
37
+
-`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).
- Selenium and chromedriver dependencies automatically handled.
76
46
- Automatically spawns the Selenium server.
77
47
78
-
For a better understanding of how things work, consult the docs for respective projects listed. In particular, [Webpack](http://webpack.github.io/) and [vue-loader](http://vuejs.github.io/vue-loader).
79
-
80
-
## Common Questions
81
-
82
-
-#### What's the difference between `src/assets/` and `static/`?
83
-
84
-
Files inside `src/assets/` should be referenced via relative paths inside Vue component templates and styles. This allows them to be processed by webpack using `url-loader` and `file-loader` before copied into `/static`. This allows you to leverage features such as file naming with hashes for better caching and conditional base-64 inline-ing. You can even add [image-optimizing loaders](https://github.com/tcoopman/image-webpack-loader) to automatically optimize these images during build.
85
-
86
-
Files inside `static/` are copied directly without modification; they can be reference anywhere via root-relative paths that start with `/static/`. This is an escape hatch when you want certain assets to completely bypass webpack.
87
-
88
-
-#### How do I configure the linting rules?
89
-
90
-
The project uses [Standard](https://github.com/feross/standard) code style via ESLint. You can override the rules in `.eslintrc.js`, for example allowing semicolons by adding `"semi": [2, "always"]`.
91
-
92
-
Alternatively you can use a different config altogether, for example [eslint-config-airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb). Install it and change the `"extends"` field in `.eslintrc.js`.
93
-
94
-
-#### How do I use a CSS pre-processor inside `*.vue` files?
95
-
96
-
First, install the corresponding loader (and their peer dependencies), e.g. to use LESS:
97
-
98
-
```bash
99
-
npm install less-loader less --save-dev
100
-
```
101
-
102
-
Then in your `*.vue` files, use `<style lang="less">`. The CSS extraction has been pre-configured to work with most popular pre-processors.
103
-
104
-
For SASS:
105
-
106
-
```bash
107
-
npm install sass-loader node-sass --save-dev
108
-
```
109
-
110
-
Note that `lang="sass"` assumes SASS's indented syntax; Use `lang="scss"` if you want the CSS-superset syntax.
111
-
112
-
-#### How do I work with an existing backend server during development?
113
-
114
-
You can edit `proxyTable` in [`build/dev-server.js`](https://github.com/vuejs-templates/webpack/blob/master/template/build/dev-server.js#L11) to proxy certain requests to your backend server.
115
-
116
-
-#### How do I deploy built assets with my backend framework?
117
-
118
-
Your backend framework may come with a convention for where static assets should live, and the default generated file structure may need to be adjusted. Here's what you need to do:
119
-
120
-
- Edit [`output.publicPath`](https://github.com/vuejs-templates/webpack/blob/master/template/build/webpack.base.conf.js#L11) to be the URL path where your backend framework serves static assets, e.g. `/public/`.
121
-
122
-
- After running `npm run build`, copy the contents of `dist/index.html` into the appropriate server-side template, and copy everything in `dist/static` to the public/static directory of your backend framework. You can automate this by adding custom scripts in `build/build.js`.
123
-
124
-
-#### How do I run unit tests in more browsers?
125
-
126
-
You can run the tests in multiple real browsers by installing more [karma launchers](http://karma-runner.github.io/0.13/config/browsers.html) and adjusting the `browsers` field in [`test/unit/karma.conf.js`](https://github.com/vuejs-templates/webpack/blob/master/template/test/unit/karma.conf.js#L46).
127
-
128
-
-#### How do I run e2e tests in more browsers?
129
-
130
-
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](http://nightwatchjs.org/guide#selenium-settings) for more details.
131
-
132
-
-#### Is there a way to prerender certain routes for SEO?
133
-
134
-
If you want to prerender routes that will not significantly change once pushed to production, use this Webpack plugin: [prerender-spa-plugin](https://www.npmjs.com/package/prerender-spa-plugin), which has been tested for use with Vue. For pages that _do_ frequently change, [Prerender.io](https://prerender.io/) and [Netlify](https://www.netlify.com/pricing) both offer plans for regularly re-prerendering your content for search engines.
135
-
136
48
### Fork It And Make Your Own
137
49
138
50
You can fork this repo to create your own boilerplate, and use it with `vue-cli`:
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.
4
+
5
+
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.
6
+
7
+
## Quickstart
8
+
9
+
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.**
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.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. `config.js` exposes some common options that allows you to configure the Webpack output so that when you run `npm run build`, the assets are generated in the right place.
4
+
5
+
Let's take a look at the default `config.js`:
6
+
7
+
```js
8
+
var path =require('path')
9
+
10
+
module.exports= {
11
+
build: {
12
+
index:path.resolve(__dirname, 'dist/index.html'),
13
+
assetsRoot:path.resolve(__dirname, 'dist'),
14
+
assetsSubDirectory:'static',
15
+
assetsPublicPath:'/',
16
+
productionSourceMap:true
17
+
},
18
+
dev: {
19
+
port:8080,
20
+
proxyTable: {}
21
+
}
22
+
}
23
+
```
24
+
25
+
Inside the `build` section, we have the following options:
26
+
27
+
### `build.index`
28
+
29
+
> Must be an absolute path on your local file system.
30
+
31
+
This is where the `index.html` (with injected asset URLs) will be generated.
32
+
33
+
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.
34
+
35
+
### `build.assetsRoot`
36
+
37
+
> Must be an absolute path on your local file system.
38
+
39
+
This should point to the root directory that contains all the static assets for your app. For example, `public/` for both Rails/Laravel.
40
+
41
+
### `build.assetsSubDirectory`
42
+
43
+
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`.
44
+
45
+
This directory will be cleaned before each build, so it should only contain assets generated by the build.
46
+
47
+
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.
48
+
49
+
### `build.assetsPublicPath`
50
+
51
+
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`.
52
+
53
+
### `build.productionSourceMap`
54
+
55
+
Whether to generate source maps for production build.
56
+
57
+
### `dev.port`
58
+
59
+
Specify the port for the dev server to listen to.
60
+
61
+
### `dev.proxyTable`
62
+
63
+
Define proxy rules for the dev server. See [API Proxying During Development](proxy.md) for more details.
All build commands are executed via [NPM Scripts](https://docs.npmjs.com/misc/scripts).
4
+
5
+
### `npm run dev`
6
+
7
+
> Starts a Node.js local development server. See [API Proxying During Development](proxy.md) for more details.
8
+
9
+
- Webpack + `vue-loader` for single file Vue components.
10
+
- State preserving hot-reload
11
+
- State preserving compilation error overlay
12
+
- Lint-on-save with ESLint
13
+
- Source maps
14
+
15
+
### `npm run build`
16
+
17
+
> Build assets for production. See [Integrating with Backend Framework](backend.md) for more details.
18
+
19
+
- JavaScript minified with [UglifyJS](https://github.com/mishoo/UglifyJS2).
20
+
- HTML minified with [html-minifier](https://github.com/kangax/html-minifier).
21
+
- CSS across all components extracted into a single file and minified with [cssnano](https://github.com/ben-eb/cssnano).
22
+
- 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.
23
+
- Also see [deployment notes](#how-do-i-deploy-built-assets-with-my-backend-framework).
24
+
25
+
### `npm run unit`
26
+
27
+
> Run unit tests in PhantomJS with [Karma](http://karma-runner.github.io/0.13/index.html). See [Unit Testing](unit.md) for more details.
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.
4
+
5
+
Let's take a look at the files in the `test/e2e` directory:
6
+
7
+
-`runner.js`
8
+
9
+
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`.
10
+
11
+
-`nightwatch.conf.js`
12
+
13
+
Nightwatch configuration file. See [Nightwatch's docs on configuration](http://nightwatchjs.org/guide#settings-file) for more details.
14
+
15
+
-`custom-assertions/`
16
+
17
+
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.
18
+
19
+
-`specs/`
20
+
21
+
You 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.
22
+
23
+
### Running Tests in More Browsers
24
+
25
+
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.
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.
4
+
5
+
If you are not happy with the default linting rules, you have several options:
6
+
7
+
1. Overwrite individual rules in `.eslintrc.js`. For example, you can add the following rule to enforce semicolons instead of omitting them:
8
+
9
+
```js
10
+
"semi": [2, "always"]
11
+
```
12
+
13
+
2. Remove the `extends: 'standard'` line in `.eslintrc.js` and use a completely custom eslint config. See [ESLint documentation](http://eslint.org/docs/user-guide/configuring) for more details.
14
+
15
+
3. Use a different ESLint preset, for example [eslint-config-airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb).
16
+
17
+
4. Disable linting altogether: comment out the `module.preLoaders` block in `build/webpack.base.conf.js`.
18
+
19
+
You will also need to disable linting if you are using a compile-to-JavaScript language, e.g. CoffeeScript.
If you want to prerender routes that will not significantly change once pushed to production, use this Webpack plugin: [prerender-spa-plugin](https://www.npmjs.com/package/prerender-spa-plugin), which has been tested for use with Vue. For pages that _do_ frequently change, [Prerender.io](https://prerender.io/) and [Netlify](https://www.netlify.com/pricing) both offer plans for regularly re-prerendering your content for search engines.
When integrating this boilerplate with an existing backend, a common need is to access the backend API when using the dev server. To achieve that, we can run the dev server and the API backend side-by-side (or remotely), and let the dev server proxy all API requests to the actual backend.
4
+
5
+
To configure the proxy rules, edit `dev.proxyTable` option in `config.js`. The dev server is using [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) for proxying, so you should refer to its docs for detailed usage. But here's a simple example:
6
+
7
+
```js
8
+
// config.js
9
+
module.exports= {
10
+
// ...
11
+
dev: {
12
+
proxyTable: {
13
+
// proxy all requests starting with /api to jsonplaceholder
14
+
'/api': {
15
+
target:'http://jsonplaceholder.typicode.com',
16
+
changeOrigin:true,
17
+
pathRewrite: {
18
+
'^/api':''
19
+
}
20
+
}
21
+
}
22
+
}
23
+
}
24
+
```
25
+
26
+
The above example will proxy the request `/api/posts/1` to `http://jsonplaceholder.typicode.com/posts/1`.
You will notice in the project structure we have two directories for static assets: `src/assets` and `static/`. What is the difference between them?
4
+
5
+
### Webpacked Assets
6
+
7
+
To answer this question, we first need to understand how Webpack deals with static assets. In `*.vue` components, all your templates and CSS are parsed by `vue-html-loader` and `css-loader` to look for relative asset URLs. For example, in `<img src="./logo.png">` and `background: url(./logo.png)`, `"./logo.png"` is a relative asset path and will be **resolved by Webpack as a module dependency**.
8
+
9
+
Because `logo.png` is not JavaScript, we need to use `url-loader` and `file-loader` to process it. This boilerplate has already configured these loaders for you, so you basically get features such as filename fingerprinting and conditional bas64 inlining for free, while being able to use relative paths everywhere.
10
+
11
+
Because these assets may be inlined/copied/renamed during build, they are essentially part of your source code. This is why it is recommended to place Webpack-processed static assets inside `/src`, along side other source files. In fact, you don't even have to put them all in `/src/assets`: you can organize them based on the module/component using them. For example, you can put each component in its own directory, with its static assets right next to it.
12
+
13
+
### "Real" Static Assets
14
+
15
+
In comparison, files in `static/` are not processed by Webpack at all: they are directly copied to their final destination as-is, with the same filename. You must reference these files using absolute paths, which is determined by joining `build.assetsPublicPath` and `build.assetsSubDirectory` in `config.js`.
16
+
17
+
As an example, with the following default values:
18
+
19
+
```js
20
+
// config.js
21
+
module.exports= {
22
+
// ...
23
+
build: {
24
+
assetsPublicPath:'/',
25
+
assetsSubDirectory:'static'
26
+
}
27
+
}
28
+
```
29
+
30
+
Any file placed in `static/` should be referenced using the absolute URL `/static/[filename]`. If you change `assetSubDirectory` to `assets`, then these URLs will need to be changed to `/assets/[filename]`.
31
+
32
+
We will learn more about the config file in the [next section](backend.md).
│ └── assets/ # module assets (processed by webpack)
14
+
│ └── ...
15
+
├── static/ # pure static assets (directly copied)
16
+
├── test/
17
+
│ └── unit/ # unit tests
18
+
│ │ ├── specs/ # test spec files
19
+
│ │ ├── index.js # test build entry file
20
+
│ │ └── karma.conf.js # test runner config file
21
+
│ └── e2e/ # e2e tests
22
+
│ │ ├── specs/ # test spec files
23
+
│ │ ├── custom-assertions/ # custom assertions for e2e tests
24
+
│ │ ├── runner.js # test runner script
25
+
│ │ └── nightwatch.conf.js # test runner config file
26
+
├── .babelrc # babel config
27
+
├── .eslintrc.js # eslint config
28
+
├── index.html # index.html template
29
+
└── package.json # build scripts and dependencies
30
+
```
31
+
32
+
### `config.js`
33
+
34
+
This is the main configuration file that exposes some of the most common configuration options for the build setup. See [API Proxying During Development](proxy.md) and [Integrating with Backend Framework](backend.md) for more details.
35
+
36
+
### `build/`
37
+
38
+
This directory holds the actual configurations for both the development server and the production webpack build. Normally you don't need to touch these files unless you want to customize Webpack loaders, in which case you should probably look at `build/webpack.base.conf.js`.
39
+
40
+
### `src/`
41
+
42
+
This is where most of your application code will live in. How to structure everything inside this directory is largely up to you; if you are using Vuex, you can consult the [recommendations for Vuex applications](http://vuex.vuejs.org/en/structure.html).
43
+
44
+
### `static/`
45
+
46
+
This directory is an escape hatch for static assets that you do not want to process with Webpack. They will be directly copied into the same directory where webpack-built assets are generated.
47
+
48
+
See [Handling Static Assets](static.md) for more details.
49
+
50
+
### `test/unit`
51
+
52
+
Contains unit test related files. See [Unit Testing](unit.md) for more details.
53
+
54
+
### `test/e2e`
55
+
56
+
Contains e2e test related files. See [End-to-end Testing](e2e.md) for more details.
57
+
58
+
### `index.html`
59
+
60
+
This is the **template**`index.html` for our single page application. During development and builds, Webpack will generate assets, and the URLs for those generated assets will automatically injected into this template to render the final HTML.
61
+
62
+
### `package.json`
63
+
64
+
The NPM package meta file that contains all the build dependencies and [build commands](commands.md).
An overview of the tools used by this boilerplate for unit testing:
4
+
5
+
-[Karma](http://karma-runner.github.io/0.13/index.html): the test runner that launches browsers, runs the tests and reports the results to us.
6
+
-[karma-webpack](https://github.com/webpack/karma-webpack): the plugin for Karma that bundles our tests using Webpack.
7
+
-[Mocha](https://mochajs.org/): the test framework that we write test specs with.
8
+
-[Chai](http://chaijs.com/): test assertion library that provides better assertion syntax.
9
+
-[Sinon](http://sinonjs.org/): test utility library that provides spies, stubs and mocks.
10
+
11
+
Chai and Sinon are integrated using [karma-sinon-chai](https://github.com/kmees/karma-sinon-chai), so all Chai interfaces (`should`, `expect`, `assert`) and `sinon` are globally available in test files.
12
+
13
+
And the files:
14
+
15
+
-`index.js`
16
+
17
+
This the entry file used by `karma-webpack` to bundle all the test code and source code (for coverage purposes). You can ignore it for the most part.
18
+
19
+
-`specs/`
20
+
21
+
This directory is where you write your actual tests. You can use full ES2015 and all supported Webpack loaders in your tests.
22
+
23
+
-`karma.conf.js`
24
+
25
+
This is the Karma configuration file. See [Karma docs](http://karma-runner.github.io/0.13/index.html) for more details.
26
+
27
+
## Running Tests in More Browsers
28
+
29
+
You can run the tests in multiple real browsers by installing more [karma launchers](http://karma-runner.github.io/0.13/config/browsers.html) and adjusting the `browsers` field in `test/unit/karma.conf.js`.
30
+
31
+
## Mocking Dependencies
32
+
33
+
This boilerplate comes with [inject-laoder](https://github.com/plasticine/inject-loader) installed by default. For usage with `*.vue` components, see [vue-loader docs on testing with mocks](http://vuejs.github.io/vue-loader/workflow/testing-with-mocks.html).
0 commit comments