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`.
0 commit comments