diff --git a/.eslintrc b/.eslintrc new file mode 100644 index 000000000..d0dd64cbb --- /dev/null +++ b/.eslintrc @@ -0,0 +1,4 @@ +{ + "root": true, + "extends": "vue" +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 47ac721a2..000000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: 'ci' -on: - push: - branches: - - '**' - pull_request: - branches: - - main -jobs: - test-webpack4: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 - with: - node-version: '16' - cache: 'pnpm' - - run: pnpm install - - run: pnpm pretest:webpack4 - - run: pnpm test:webpack4 - - test-webpack5: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 - with: - node-version: '16' - cache: 'pnpm' - - run: pnpm install - - run: pnpm pretest - - run: pnpm test - - test-webpack5-inline-match-resource: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 - with: - node-version: '16' - cache: 'pnpm' - - run: pnpm install - - run: pnpm pretest:match-resource - - run: pnpm test:match-resource diff --git a/.gitignore b/.gitignore index 7ff6b0d08..6c2848eb9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,5 @@ -*.log -.DS_Store node_modules -dist -dist-ssr -link.sh -.cache -TODOs.md -coverage -.vscode +npm-debug.log +test/output +docs/_book +.DS_Store diff --git a/.node-version b/.node-version deleted file mode 100644 index 9e15be387..000000000 --- a/.node-version +++ /dev/null @@ -1 +0,0 @@ -v16.20.0 diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index f5a1bdcdd..000000000 --- a/.prettierrc +++ /dev/null @@ -1,3 +0,0 @@ -semi: false -singleQuote: true -printWidth: 80 diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 3662b3700..000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "typescript.tsdk": "node_modules/typescript/lib" -} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 311c35af7..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,533 +0,0 @@ -## [17.4.2](https://github.com/vuejs/vue-loader/compare/v17.4.1...v17.4.2) (2023-12-30) - - -### Bug Fixes - -* pass compilerOptions to sfc parse & re-enable AST reuse ([d2a2e05](https://github.com/vuejs/vue-loader/commit/d2a2e051c3d985d1ae6bb468749b24543631b482)) - - - -## [17.4.1](https://github.com/vuejs/vue-loader/compare/v17.4.0...v17.4.1) (2023-12-30) - - -### Bug Fixes - -* (temporarily) disable template ast reuse ([31b03af](https://github.com/vuejs/vue-loader/commit/31b03af121edbe70337f538b1def95acbef4d0f1)) - - - -# [17.4.0](https://github.com/vuejs/vue-loader/compare/v17.3.1...v17.4.0) (2023-12-25) - - -### Features - -* leverage ast reuse in 3.4 ([479835f](https://github.com/vuejs/vue-loader/commit/479835fe751691a39c62cda12bffeef9e6830443)) - - - -## [17.3.1](https://github.com/vuejs/vue-loader/compare/v17.3.0...v17.3.1) (2023-10-31) - - -### Bug Fixes - -* do not skip style post loader for v-bind() in CSS ([d7071bb](https://github.com/vuejs/vue-loader/commit/d7071bbdeb45518c053bdae8eb7de52fc598adc6)), closes [#2061](https://github.com/vuejs/vue-loader/issues/2061) - - -# [17.3.0](https://github.com/vuejs/vue-loader/compare/v17.2.2...v17.3.0) (2023-10-07) - - -### Bug Fixes - -* re-use ident of vue rule for template compiler, fixes [#2029](https://github.com/vuejs/vue-loader/issues/2029) ([#2030](https://github.com/vuejs/vue-loader/issues/2030)) ([b50fa56](https://github.com/vuejs/vue-loader/commit/b50fa5665f2cbc1c0b8e18f65dd3adf1dfe848dc)) - - -### Features - -* skip normal css files without scoped flag in stylePostLoader ([#2053](https://github.com/vuejs/vue-loader/issues/2053)) ([98782e7](https://github.com/vuejs/vue-loader/commit/98782e794fadca83b600b047b55aa6f0c230cc25)) - - - -## [17.2.2](https://github.com/vuejs/vue-loader/compare/v17.2.1...v17.2.2) (2023-06-02) - - -### Bug Fixes - -* windows path for `experiments.css` ([#2049](https://github.com/vuejs/vue-loader/issues/2049)) ([f3f45df](https://github.com/vuejs/vue-loader/commit/f3f45df925bcd80307232e7410ead355f87953d3)) - - - -## [17.2.1](https://github.com/vuejs/vue-loader/compare/v17.1.2...v17.2.1) (2023-06-01) - - -### Features - -* A new `experimentalInlineMatchResource` option (webpack 5 only), which leverages webpack 5's inline match resource feature and works well with the [`experiments.css`](https://webpack.js.org/configuration/experiments/#experimentscss) feature ([#2046](https://github.com/vuejs/vue-loader/issues/2046)) ([3149f6d](https://github.com/vuejs/vue-loader/commit/3149f6d69c2f456bdcfa23acc0da93473a93a764)) - - -Note: v17.2.0 was released by accident, it has the same content as v17.1.2, therefore not included in the changelog. - - -## [17.1.2](https://github.com/vuejs/vue-loader/compare/v17.1.1...v17.1.2) (2023-05-29) - - -### Bug Fixes - -* keep build stable when run in a different path ([#2040](https://github.com/vuejs/vue-loader/issues/2040)) ([a81dc0f](https://github.com/vuejs/vue-loader/commit/a81dc0f573d216eefa13b0275f3fc147bf3e2ef3)) -* properly close the watcher after tests ([40b93b9](https://github.com/vuejs/vue-loader/commit/40b93b9c2722e85a000de62e3eb8bc02facafd10)) - - - -## [17.1.1](https://github.com/vuejs/vue-loader/compare/v17.1.0...v17.1.1) (2023-05-11) - - -### Bug Fixes - -* support propsDestructure and defineModel options ([6269698](https://github.com/vuejs/vue-loader/commit/6269698f9fda37f0e3849db3e8b8e67ad1862f57)) - - - -# [17.1.0](https://github.com/vuejs/vue-loader/compare/v17.1.0-beta.0...v17.1.0) (2023-04-26) - - -### Bug Fixes - -* do not throw when `Rule.layer` ([#2000](https://github.com/vuejs/vue-loader/issues/2000)) ([ef589df](https://github.com/vuejs/vue-loader/commit/ef589df2956506a5a7bbc050c476501d32dd8469)) - - - -# [17.1.0-beta.0](https://github.com/vuejs/vue-loader/compare/v17.0.1...v17.1.0-beta.0) (2023-04-19) - - -### Bug Fixes - -* reference project compiler, fixes [#2031](https://github.com/vuejs/vue-loader/issues/2031) ([#2038](https://github.com/vuejs/vue-loader/issues/2038)) ([cc6fa9e](https://github.com/vuejs/vue-loader/commit/cc6fa9ebf85972a08fc8bbc359b0093b15790745)) - - -### Features - -* support 3.3 imported types hmr ([bbd98fc](https://github.com/vuejs/vue-loader/commit/bbd98fc8bdc17fcbffb456a5ffe772bc184f22e4)) - - - -## [17.0.1](https://github.com/vuejs/vue-loader/compare/v17.0.0...v17.0.1) (2022-10-28) - - -### Bug Fixes - -* add `vue` and `@vue/compiler-sfc` to optional peerDependencies ([df0ded5](https://github.com/vuejs/vue-loader/commit/df0ded5356864b9923da8f89ff33db1ae6c2402f)), closes [#1944](https://github.com/vuejs/vue-loader/issues/1944) -* merge custom queries rather than appending ([#1911](https://github.com/vuejs/vue-loader/issues/1911)) ([9e4249a](https://github.com/vuejs/vue-loader/commit/9e4249a548ceb04ead46fff9b68e9b2676b4c692)) - - - -## [17.0.1](https://github.com/vuejs/vue-loader/compare/v16.8.3...v17.0.1) (2022-10-28) - - -### Bug Fixes - -* add `vue` and `@vue/compiler-sfc` to optional peerDependencies ([df0ded5](https://github.com/vuejs/vue-loader/commit/df0ded5356864b9923da8f89ff33db1ae6c2402f)), closes [#1944](https://github.com/vuejs/vue-loader/issues/1944) -* merge custom queries rather than appending ([#1911](https://github.com/vuejs/vue-loader/issues/1911)) ([9e4249a](https://github.com/vuejs/vue-loader/commit/9e4249a548ceb04ead46fff9b68e9b2676b4c692)) - - - -# [17.0.0](https://github.com/vuejs/vue-loader/compare/v16.8.3...v17.0.0) (2021-12-12) - - -### Features - -* support `reactivityTransform` option ([e07490e](https://github.com/vuejs/vue-loader/commit/e07490ec8b8ac9e00050251d6f0e697fb1f3bf3c)) - - -### BREAKING CHANGES - -* remove `refSugar` option, require `vue@^3.2.13` - - - -## [16.8.3](https://github.com/vuejs/vue-loader/compare/v16.8.2...v16.8.3) (2021-11-04) - - -### Bug Fixes - -* HMR not working correctly with vue-class-component components ([#1897](https://github.com/vuejs/vue-loader/issues/1897)) ([76b1448](https://github.com/vuejs/vue-loader/commit/76b1448eb227c42e1791a691a86782b7a8cacfc0)) - - - -## [16.8.3](https://github.com/vuejs/vue-loader/compare/v16.8.2...v16.8.3) (2021-11-04) - - -### Bug Fixes - -* HMR not working correctly with vue-class-component components ([#1897](https://github.com/vuejs/vue-loader/issues/1897)) ([76b1448](https://github.com/vuejs/vue-loader/commit/76b1448eb227c42e1791a691a86782b7a8cacfc0)) - - - -## [16.8.2](https://github.com/vuejs/vue-loader/compare/v16.8.1...v16.8.2) (2021-10-26) - - -### Bug Fixes - -* should allow chaining with loaders for non-vue files ([#1889](https://github.com/vuejs/vue-loader/issues/1889)) ([f32f953](https://github.com/vuejs/vue-loader/commit/f32f9538ea34fc08e1a28622227896241847690f)), closes [#1879](https://github.com/vuejs/vue-loader/issues/1879) [#1883](https://github.com/vuejs/vue-loader/issues/1883) [#1890](https://github.com/vuejs/vue-loader/issues/1890) -* **plugin:** use compiler.webpack when possible ([#1884](https://github.com/vuejs/vue-loader/issues/1884)) ([820d23c](https://github.com/vuejs/vue-loader/commit/820d23cbf16013dae894e0d84ed9da6e58a37584)) - - - -## [16.8.1](https://github.com/vuejs/vue-loader/compare/v16.8.0...v16.8.1) (2021-09-22) - - -### Bug Fixes - -* fix template options resolving for ts ([91f581b](https://github.com/vuejs/vue-loader/commit/91f581b99644119b68e586a0b642fff3811c8741)) - -# [16.8.0](https://github.com/vuejs/vue-loader/compare/v16.7.1...v16.8.0) (2021-09-22) - - -### Bug Fixes - -* **hmr:** fix hmr regression ([bacc6a9](https://github.com/vuejs/vue-loader/commit/bacc6a9eeca40d6028a2d9a5f6ee02e6c8574abd)) - - -### Features - -* enableTsInTemplate option ([7613534](https://github.com/vuejs/vue-loader/commit/7613534954b83489a060860b9525a0d121023c5b)) - - - When used with `ts-loader`, due to `ts-loader`'s cache invalidation behavior, it sometimes prevents the template from being hot-reloaded in isolation, causing the component to reload despite only the template being edited. If this is annoying, you can set this option to `false` (and avoid using TS expressions in templates). - - - Alternatively, leave this option on (by default) and use [`esbuild-loader`](https://github.com/privatenumber/esbuild-loader) to transpile TS instead, which doesn't suffer from this problem (it's also a lot faster). However, do note you will need to rely on TS type checking from other sources (e.g. IDE or `vue-tsc`). - -## [16.7.1](https://github.com/vuejs/vue-loader/compare/v16.7.0...v16.7.1) (2021-09-22) - - -### Bug Fixes - -* remove pure annotation for custom blocks ([cd891e5](https://github.com/vuejs/vue-loader/commit/cd891e593bf7f8aff852f1d47fda2337de661bea)) - - -# [16.7.0](https://github.com/vuejs/vue-loader/compare/v16.6.0...v16.7.0) (2021-09-21) - - -### Features - -* support optional @vue/compiler-sfc peer dep ([21725a4](https://github.com/vuejs/vue-loader/commit/21725a4ebc9c8d7f8a590d700017759327e21c2e)) - - -# [16.6.0](https://github.com/vuejs/vue-loader/compare/v16.5.0...v16.6.0) (2021-09-20) - - -### Bug Fixes - -* generate treeshaking friendly code ([11e3cb8](https://github.com/vuejs/vue-loader/commit/11e3cb8a8a4a4e0aedc2978ce6d7e549a61de3d7)) - - -### Features - -* support ts in template expressions ([573fbd2](https://github.com/vuejs/vue-loader/commit/573fbd2e72c3246c2daadb8d8c053464c964cfe3)) - - -# [16.5.0](https://github.com/vuejs/vue-loader/compare/v16.4.1...v16.5.0) (2021-08-07) - -* Custom Elements mode behavior changed: now only inlines the CSS and no longer exports the custom element constructor (exports the component as in normal mode). Users now need to explicitly call `defineCustomElement` on the component. This allows the custom element to be defined using an async version of the source component. - - -## [16.4.1](https://github.com/vuejs/vue-loader/compare/v16.4.0...v16.4.1) (2021-08-02) - - -### Bug Fixes - -* fix webpack 5.48 compatibility ([b94289c](https://github.com/vuejs/vue-loader/commit/b94289c9fb395556100ec121529dfe676280d3cd)), closes [#1859](https://github.com/vuejs/vue-loader/issues/1859) - - -# [16.4.0](https://github.com/vuejs/vue-loader/compare/v16.3.3...v16.4.0) (2021-07-30) - - -### Features - -* customElement option support for Vue 3.2 ([e19fcda](https://github.com/vuejs/vue-loader/commit/e19fcdaa62c4aa5d826c33a0e7fb8786904ee225)) - - -## [16.3.3](https://github.com/vuejs/vue-loader/compare/v16.3.2...v16.3.3) (2021-07-21) - - -### Bug Fixes - -* mark @vue/compiler-sfc as an optional peer dependency ([089473a](https://github.com/vuejs/vue-loader/commit/089473af97077b8e14b3feff48d32d2733ad792c)) - - - -## [16.3.2](https://github.com/vuejs/vue-loader/compare/v16.3.1...v16.3.2) (2021-07-20) - - -### Bug Fixes - -* add undeclared peer dependency `webpack` and `@vue/compiler-sfc` ([#1853](https://github.com/vuejs/vue-loader/issues/1853)) ([330d672](https://github.com/vuejs/vue-loader/commit/330d672fb344fddefec98e170587d93876a9e354)) - - - -## [16.3.1](https://github.com/vuejs/vue-loader/compare/v16.3.0...v16.3.1) (2021-07-16) - - -### Bug Fixes - -* pick up production env in thread-loader context ([821a3a3](https://github.com/vuejs/vue-loader/commit/821a3a35f04cda3154a9341898225f61d72b3f05)), closes [vuejs/vue-next#3921](https://github.com/vuejs/vue-next/issues/3921) - - - -# [16.3.0](https://github.com/vuejs/vue-loader/compare/v16.2.0...v16.3.0) (2021-06-29) - - -### Features - -* pass on compilerOptions and refSugar when using ` - - -``` - -There are many cool features provided by `vue-loader`: - -- Allows using other webpack loaders for each part of a Vue component, for example Sass for ` +``` + +Under the hood, the text content inside the ` +``` + +However, note this makes your Vue component Webpack-specific and not compatible with Browserify and [vueify](https://github.com/vuejs/vueify). **If you intend to ship your Vue component as a reusable 3rd-party component, avoid using this syntax.** diff --git a/docs/en/features/css-modules.md b/docs/en/features/css-modules.md new file mode 100644 index 000000000..b69b74294 --- /dev/null +++ b/docs/en/features/css-modules.md @@ -0,0 +1,56 @@ +# CSS Modules + +[CSS Modules](https://github.com/css-modules/css-modules) aims to solve class & animation name conflicts. It replaces all the local names with unique hashes and provides a name-to-hash map. So you can write short and general names without worrying any conflict! + +With vue-loader, you can simply use CSS Modules with ` + + + + +``` + +If you need mutiple ` + + + +``` + +## Tips + +1. Animation names also get transformed. So, it's recommended to use animations with CSS modules. + +2. You can use `scoped` and `module` together to avoid problems in descendant selectors. + +3. Use `module` only (without `scoped`), you are able to style ``s and children components. But styling children components breaks the principle of components. You can put `` in a classed wrapper and style it under that class. + +4. You can expose the class name of component's root element for theming. diff --git a/docs/en/features/es2015.md b/docs/en/features/es2015.md new file mode 100644 index 000000000..dae2dd4f8 --- /dev/null +++ b/docs/en/features/es2015.md @@ -0,0 +1,92 @@ +# ES2015 and Babel Configuration + +`vue-loader` ships with ES2015 (aka ES6) enabled by default in ` +``` + +We are using ES2015's Object literal shorthand here to define the child components. `{ ComponentA }` is simply shorthand for `{ ComponentA: ComponentA }`. Vue will automatically convert the key to `component-a`, so you can use the imported component in the template as ``. + +### Using Custom Babel Configuration + +> **Compatibility Note**: `vue-loader` 7.0+ uses Babel 6. If you need to use Babel 5 for transpiling your code, use vue-loader 6.x. + +The default Babel options used for scripts inside Vue components are: + +``` json +{ + "presets": ["es2015"], + "plugins": ["transform-runtime"] +} +``` + +If you want to use custom presets or plugins, for example, to enable stage-0 language features, install the preset/plugin and then add a `babel` field in your Webpack config: + +``` bash +npm install babel-preset-stage-0 --save-dev +``` + +``` js +// webpack.config.js +module.exports = { + // other configs... + babel: { + // enable stage 0 babel transforms. + presets: ['es2015', 'stage-0'], + plugins: ['transform-runtime'] + } +} +``` + +Alternatively, you can add a `.babelrc` file at the root of your project. + +### Compiling `.js` Files with Babel + +Since we are already using Babel, most likely you'll want to compile your normal `.js` files too! Here's how to do it in your Webpack config: + +``` js +// webpack.config.js +module.exports = { + // other options ... + module: { + loaders: [ + { + // use vue-loader for *.vue files + test: /\.vue$/, + loader: 'vue' + }, + { + // use babel-loader for *.js files + test: /\.js$/, + loader: 'babel', + // important: exclude files in node_modules + // otherwise it's going to be really slow! + exclude: /node_modules/ + } + ] + }, + // if you are using babel-loader directly then + // the babel config block becomes required. + babel: { + presets: ['es2015'], + plugins: ['transform-runtime'] + } +} +``` diff --git a/docs/en/features/hot-reload.md b/docs/en/features/hot-reload.md new file mode 100644 index 000000000..57672d606 --- /dev/null +++ b/docs/en/features/hot-reload.md @@ -0,0 +1,42 @@ +# Hot Reload + +"Hot Reload" is not simply reloading the page when you edit a file. With hot reload enabled, when you edit a `*.vue` file, all instances of that component will be swapped in **without reloading the page**. It even preserves the current state of your app and these swapped components! This dramatically improves the development experience when you are tweaking the templates or styling of your components. + +![hot-reload](http://blog.evanyou.me/images/vue-hot.gif) + +### Enabling Hot Reload + +The easiest setup for enabling hot reload is what we outlined in the [basic tutorial](../start/tutorial.md): + +``` js +// package.json +... +"scripts": { + "dev": "webpack-dev-server --inline --hot" +} +... +``` + +This is assuming that you are serving the same `index.html` from the root of your project. By default, Webpack dev server uses the current working directory as its content base and serves all static files in the directory. + +Run `npm run dev` and the static app will be served at `http://localhost:8080`. + +### Hot Reload Notes + +- When a component is hot-reloaded, its current state is preserved. However, the component itself is destroyed and recreated, so all of its lifecycle hooks will be called accordingly. Make sure to properly teardown any side effects in your lifecycle hooks. + +- Private state for child components of a hot-reloaded component is not guaranteed to be preserved across reloads. + +- A root Vue instance or a manually mounted instance cannot be hot-reloaded. It will always force a full reload. + +### Configuration Tips + +- You can use the `--port` option to serve at a different port. + +- If your file structure is different, you will have to configure `output.publicPath` in your Webpack config and the `--content-base` option of your webpack-dev-server command accordingly. + +- If you are using the HTML5 history API (for example with `vue-router`), you will also want to add the `--history-api-fallback` option. + +- Consult the [Webpack dev server documentation](https://webpack.github.io/docs/webpack-dev-server.html) for advanced topics such as combining the dev server with another backend server. + +- Finally, if you have an existing [Express](http://expressjs.com/en/index.html) based Node.js backend, you can just add the [Webpack dev middleware](https://webpack.github.io/docs/webpack-dev-middleware.html) to serve your webpack bundle. diff --git a/docs/en/features/postcss.md b/docs/en/features/postcss.md new file mode 100644 index 000000000..ad8352edc --- /dev/null +++ b/docs/en/features/postcss.md @@ -0,0 +1,64 @@ +# PostCSS and Autoprefixer + +Any CSS output processed by `vue-loader` is piped through [PostCSS](https://github.com/postcss/postcss) for scoped CSS rewriting and auto-prefixed by default using [autoprefixer](https://github.com/postcss/autoprefixer). + +### Configuring Autoprefixer + +You can configure autoprefixer using the `autoprefixer` option under the `vue` section of your webpack config. See possible [autoprefixer options](https://github.com/postcss/autoprefixer#options). Also, you can pass in `false` to disable autoprefixing. + +Example: + +``` js +// webpack.config.js +module.exports = { + // other options... + module: { + loaders: [ + { + test: /\.vue$/, + loader: 'vue' + } + ] + }, + // vue-loader configurations + vue: { + // configure autoprefixer + autoprefixer: { + browsers: ['last 2 versions'] + } + } +} +``` + +### Using Custom PostCSS Plugins + +To use custom PostCSS plugins, pass an array to the `postcss` option under the `vue` section. Example using [CSSNext](http://cssnext.io/): + +``` js +// webpack.config.js +module.exports = { + // other configs... + vue: { + // use custom postcss plugins + postcss: [require('postcss-cssnext')()], + // disable vue-loader autoprefixing. + // this is a good idea since cssnext comes with it too. + autoprefixer: false + } +} +``` + +In addition to providing an Array of plugins, the `postcss` option also accepts: + +- A function that returns an array of plugins; + +- An object that contains options to be passed to the PostCSS processor. This is useful when you are using PostCSS projects that relies on custom parser/stringifiers: + + ``` js + postcss: { + plugins: [...], // list of plugins + options: { + parser: sugarss // use sugarss parser + } + } + ``` diff --git a/docs/en/features/scoped-css.md b/docs/en/features/scoped-css.md new file mode 100644 index 000000000..f2bb9d1e9 --- /dev/null +++ b/docs/en/features/scoped-css.md @@ -0,0 +1,51 @@ +# Scoped CSS + +When a ` + + +``` + +Into the following: + +``` html + + + +``` + +#### Notes + +1. You can include both scoped and non-scoped styles in the same component: + + ``` html + + + + ``` + +2. A child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS. + +3. Partials are not affected by scoped styles. + +4. **Scoped styles do not eliminate the need for classes**. Due to the way browsers render various CSS selectors, `p { color: red }` will be many times slower when scoped (i.e. when combined with an attribute selector). If you use classes or ids instead, such as in `.example { color: red }`, then you virtually eliminate that performance hit. [Here's a playground](http://stevesouders.com/efws/css-selectors/csscreate.php) where you can test the differences yourself. + +5. **Be careful with descendant selectors in recursive components!** For a CSS rule with the selector `.a .b`, if the element that matches `.a` contains a recursive child component, then all `.b` in that child component will be matched by the rule. To avoid class name conflicts, you can use [CSS Modules](features/css-modules.md). diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md new file mode 100644 index 000000000..beac721df --- /dev/null +++ b/docs/en/getting-started.md @@ -0,0 +1,176 @@ +# Getting Started + +### Syntax Highlighting + +First thing first, you will probably want proper syntax highlighting for `*.vue` components. Currently there are syntax highlighting support for [Sublime Text](https://github.com/vuejs/vue-syntax-highlight), [Atom](https://atom.io/packages/language-vue) and [Vim](https://github.com/posva/vim-vue). Contributions for other editors/IDEs are highly appreciated! If you are not using any pre-processors in Vue components, you can also get by by treating `*.vue` files as HTML in your editor. + +### Project Structure + +We are going to walk through setting up a Webpack + `vue-loader` project from scratch. If you are interested in ready-to-run examples, check out [vue-loader-example](https://github.com/vuejs/vue-loader-example) and [vue-hackernews](https://github.com/vuejs/vue-hackernews). However, if you are not already a Webpack expert, I highly recommend going through the following tutorial to understand how the pieces fit together. + +A simple `vue-loader` based project structure looks like this: + +``` bash +. +├── index.html +├── main.js +├── components +│   ├── App.vue +│   ├── ComponentA.vue +│   └── ComponentB.vue +├── package.json +└── webpack.config.js +``` + +### Installing Dependencies + +Before we write any code, we need to install the proper NPM dependencies. Let's run: + +``` bash +# Create a package.json file. +# fill in the questions as you desire. +npm init + +# Install everything we need +npm install\ + webpack webpack-dev-server\ + vue-loader vue-html-loader css-loader style-loader vue-hot-reload-api\ + babel-loader babel-core babel-plugin-transform-runtime babel-preset-es2015\ + babel-runtime@5\ + --save-dev +``` + +That's a lot of dependencies, I know! This is mostly because `vue-loader` need to have other webpack loaders as **peer dependencies** rather than nested dependencies so that Webpack can find them.[^(1)] + +You may also notice that we are using `babel-runtime` version 5 instead of the latest 6.x - this is [intentional](https://github.com/vuejs/vue-loader/issues/96#issuecomment-162910917). + +After proper installation, your `package.json`'s `devDependencies` field should look like this: + +``` json +... + "devDependencies": { + "babel-core": "^6.3.17", + "babel-loader": "^6.2.0", + "babel-plugin-transform-runtime": "^6.3.13", + "babel-preset-es2015": "^6.3.13", + "babel-runtime": "^5.8.34", + "css-loader": "^0.23.0", + "style-loader": "^0.13.0", + "vue-hot-reload-api": "^1.2.2", + "vue-html-loader": "^1.0.0", + "vue-loader": "^7.2.0", + "webpack": "^1.12.9", + "webpack-dev-server": "^1.14.0" + }, +... +``` + +### Configuring Webpack + +Here's the most basic Webpack configuration for `vue-loader`: + +``` js +// webpack.config.js +module.exports = { + // entry point of our application + entry: './main.js', + // where to place the compiled bundle + output: { + path: __dirname, + filename: 'build.js' + }, + module: { + // `loaders` is an array of loaders to use. + // here we are only configuring vue-loader + loaders: [ + { + test: /\.vue$/, // a regex for matching all files that end in `.vue` + loader: 'vue' // loader to use for matched files + } + ] + } +} +``` + +With the above configuration, when you write the following in your JavaScript code: + +``` js +var MyComponent = require('./my-component.vue') +``` + +Webpack knows it needs to pipe the contents of `./my-component.vue` through `vue-loader`, because the filename matches the regex we provided in the config. + +### Creating Other Files + +The app entry point, `main.js` typically looks like this: + +``` js +// main.js +var Vue = require('vue') +// require a *.vue component +var App = require('./components/App.vue') + +// mount a root Vue instance +new Vue({ + el: 'body', + components: { + // include the required component + // in the options + app: App + } +}) +``` + +Inside a `*.vue` component's ` +``` + +Next, let's create an `index.html` that simply uses the bundled file: + +``` html + + + + + +``` + +### Running It + +Finally, it's time to get it running! We will simply use [NPM scripts](https://docs.npmjs.com/misc/scripts) as our task runner, which is sufficient in most cases. Add the following to your `package.json`: + +``` json +... +"scripts": { + "dev": "webpack-dev-server --inline --hot" +} +... +``` + +Then run: + +``` bash +npm run dev +``` + +And you should see your app working at `http://localhost:8080`, with hot-reloading enabled! + +--- + +[^(1)] If you are using NPM version 2.x, when you do `npm install vue-loader --save-dev` it will install and save all the peer dependencies for you. However, if you are using NPM 3.x, these peer dependencies will no longer be automatically installed. You will have to install them explicitly like we did above. Another way to deal with it is to simply copy `vue-loader`'s peer dependencies into your `package.json`'s `devDependencies` field and then run `npm install`. diff --git a/docs/en/options.md b/docs/en/options.md new file mode 100644 index 000000000..61a1f2b47 --- /dev/null +++ b/docs/en/options.md @@ -0,0 +1,75 @@ +# Options Reference + +### loaders + +- type: `Object` + + An object specifying Webpack loaders to use for language blocks inside `*.vue` files. The key corresponds to the `lang` attribute for language blocks, if specified. The default `lang` for each type is: + + - `