Merge pull request #153 from webpack-contrib/maintenance

Maintenance

Author: jhnns

.editorconfig

@@ -1,17 +1,15 @@
-# EditorConfig is awesome: http://EditorConfig.org
+# This file is for unifying the coding style for different editors and IDEs.
+# More information at http://EditorConfig.org
 
-# top-most EditorConfig file
+# No .editorconfig files above the root directory
 root = true
 
-# Unix-style newlines with a newline ending every file
 [*]
+indent_style = space
+indent_size = 4
 charset = utf-8
-end_of_line = lf
+trim_trailing_whitespace = true
 insert_final_newline = true
-indent_style = tab
-indent_size = 4
 
-# Matches the exact files either package.json or .travis.yml
-[{package.json,.travis.yml}]
-indent_style = space
+[package.json]
 indent_size = 2

.eslintignore

@@ -0,0 +1,5 @@
+# Compiled by webpack
+test/output
+
+# Fake node_modules folder for tests
+test/node_modules

.eslintrc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "peerigon/base"
+    ],
+    "env": {
+        "node": true
+    },
+    "root": true
+}

.gitignore

@@ -1,3 +1,19 @@
+lib-cov
+*.seed
+*.log
+*.csv
+*.dat
+*.out
+*.pid
+*.gz
+
+pids
+logs
+results
+
+npm-debug.log
 /node_modules
-test/node_modules/*
-test/output/*
+coverage
+.idea
+.nyc_output
+test/output

.jshintrc

@@ -0,0 +1,14 @@
+{
+    "reporter": [
+        "lcov",
+        "text"
+    ],
+    "include": [
+        "lib/**/*.js"
+    ],
+    "lines": 92,
+    "statements": 92,
+    "functions": 100,
+    "branches": 70,
+    "check-coverage": true
+}

.npmignore

@@ -1,7 +1,9 @@
 [![npm][npm]][npm-url]
 [![node][node]][node-url]
+[![npm-stats][npm-stats]][npm-url]
 [![deps][deps]][deps-url]
-[![tests][tests]][tests-url]
+[![travis][travis]][travis-url]
+[![appveyor][appveyor]][appveyor-url]
 [![coverage][cover]][cover-url]
 [![chat][chat]][chat-url]
 
@@ -31,7 +33,7 @@ Chain the less-loader with the [css-loader](https://github.com/webpack-contrib/c
 ```js
 // webpack.config.js
 module.exports = {
-	...
+    ...
     module: {
         rules: [{
             test: /\.less$/,
@@ -47,14 +49,12 @@ module.exports = {
 };
 ```
 
-<h2 align="center">Options</h2>
-
-You can pass any Less specific options to the less-loader via [loader options](https://webpack.js.org/configuration/module/#rule-options-rule-query). See the [Less documentation](http://lesscss.org/usage/#command-line-usage-options) for all available options in dash-case. Since we're passing these options to Less programmatically, you need to pass them in camelCase here.
+You can pass any Less specific options to the less-loader via [loader options](https://webpack.js.org/configuration/module/#rule-options-rule-query). See the [Less documentation](http://lesscss.org/usage/#command-line-usage-options) for all available options in dash-case. Since we're passing these options to Less programmatically, you need to pass them in camelCase here:
 
 ```js
 // webpack.config.js
 module.exports = {
-	...
+    ...
     module: {
         rules: [{
             test: /\.less$/,
@@ -73,6 +73,54 @@ module.exports = {
 };
 ```
 
+### In production
+
+Usually, it's recommended to extract the style sheets into a dedicated file in production using the [ExtractTextPlugin](https://github.com/webpack-contrib/extract-text-webpack-plugin). This way your styles are not dependent on JavaScript:
+
+```js
+const ExtractTextPlugin = require("extract-text-webpack-plugin");
+
+const extractLess = new ExtractTextPlugin({
+    filename: "[name].[contenthash].css",
+    disable: process.env.NODE_ENV === "development"
+});
+
+module.exports = {
+    ...
+    module: {
+        rules: [{
+            test: /\.less$/,
+            loader: extractLess.extract({
+                use: [{
+                    loader: "css-loader"
+                }, {
+                    loader: "less-loader"
+                }],
+                // use style-loader in development
+                fallback: "style-loader"
+            })
+        }]
+    },
+    plugins: [
+        extractLess
+    ]
+};
+```
+
+<h2 align="center">Usage</h2>
+
+### Imports
+
+webpack provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/). The less-loader applies a Less plugin that passes all queries to the webpack resolving engine. Thus you can import your less-modules from `node_modules`. Just prepend them with a `~` which tells webpack to look-up the [`modules`](https://webpack.js.org/configuration/resolve/#resolve-modules).
+
+```css
+@import "~bootstrap/less/bootstrap";
+```
+
+It's important to only prepend it with `~`, because `~/` resolves to the home-directory. webpack needs to distinguish between `bootstrap` and `~bootstrap` because css- and less-files have no special syntax for importing relative files. Writing `@import "file"` is the same as `@import "./file";`
+
+Also please note that for [CSS modules](https://github.com/css-modules/css-modules), relative file paths do not work as expected. Please see [this issue for the explanation](https://github.com/webpack-contrib/less-loader/issues/109#issuecomment-253797335).
+
 ### Plugins
 
 In order to use [plugins](http://lesscss.org/usage/#plugins), simply set the `lessPlugins` option like this:
@@ -82,7 +130,7 @@ In order to use [plugins](http://lesscss.org/usage/#plugins), simply set the `le
 const CleanCSSPlugin = require("less-plugin-clean-css");
 
 module.exports = {
-	...
+    ...
             {
                 loader: "less-loader", options: {
                     lessPlugins: [
@@ -94,17 +142,14 @@ module.exports = {
 };
 ```
 
-### Imports
+### Extracting style sheets
 
-webpack provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/). The less-loader applies a Less plugin that passes all queries to the webpack resolving engine. Thus you can import your less-modules from `node_modules`. Just prepend them with a `~` which tells webpack to look-up the [`modules`](https://webpack.js.org/configuration/resolve/#resolve-modules).
-
-```css
-@import "~bootstrap/less/bootstrap";
-```
+Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or [hot module replacement](https://webpack.js.org/concepts/hot-module-replacement/) in development. In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) might be visible. Thus it's often still better to have them as separate files in your final production build.
 
-It's important to only prepend it with `~`, because `~/` resolves to the home-directory. webpack needs to distinguish between `bootstrap` and `~bootstrap` because css- and less-files have no special syntax for importing relative files. Writing `@import "file"` is the same as `@import "./file";`
+There are two possibilities to extract a style sheet from the bundle:
 
-Also please note that for [CSS modules](https://github.com/css-modules/css-modules), relative file paths do not work as expected. Please see [this issue for the explanation](https://github.com/webpack-contrib/less-loader/issues/109#issuecomment-253797335).
+- [extract-loader](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)
+- [extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) (more complex, but works in all use-cases)
 
 ### Source maps
 
@@ -157,6 +202,7 @@ The tests are basically just comparing the generated css with a reference css-fi
 
 
 [npm]: https://img.shields.io/npm/v/less-loader.svg
+[npm-stats]: https://img.shields.io/npm/dm/less-loader.svg
 [npm-url]: https://npmjs.com/package/less-loader
 
 [node]: https://img.shields.io/node/v/less-loader.svg
@@ -165,8 +211,11 @@ The tests are basically just comparing the generated css with a reference css-fi
 [deps]: https://david-dm.org/webpack-contrib/less-loader.svg
 [deps-url]: https://david-dm.org/webpack-contrib/less-loader
 
-[tests]: http://img.shields.io/travis/webpack-contrib/less-loader.svg
-[tests-url]: https://travis-ci.org/webpack-contrib/less-loader
+[travis]: http://img.shields.io/travis/webpack-contrib/less-loader.svg
+[travis-url]: https://travis-ci.org/webpack-contrib/less-loader
+
+[appveyor-url]: https://ci.appveyor.com/project/jhnns/less-loader/branch/master
+[appveyor]: https://ci.appveyor.com/api/projects/status/github/webpack-contrib/less-loader?svg=true
 
 [cover]: https://coveralls.io/repos/github/webpack-contrib/less-loader/badge.svg
 [cover-url]: https://coveralls.io/github/webpack-contrib/less-loader

.nycrc

@@ -0,0 +1,29 @@
+# appveyor file
+# http://www.appveyor.com/docs/appveyor-yml
+
+init:
+  - git config --global core.autocrlf input
+
+# what combinations to test
+environment:
+  matrix:
+    - nodejs_version: 7
+      job_part: test
+    - nodejs_version: 6
+      job_part: test
+    - nodejs_version: 4
+      job_part: test
+
+install:
+  - ps: Install-Product node $env:nodejs_version x64
+  - npm install
+
+build: off
+
+matrix:
+  fast_finish: true
+
+test_script:
+  - node --version
+  - npm --version
+  - cmd: npm run appveyor:%job_part%