chore: update README with examples, change lessOptions to only allow …

…objects (#324)
webpack-contrib · Mar 16, 2020 · cdb611f · cdb611f
1 parent 6fc1392
commit cdb611f
Show file tree

Hide file tree

Showing 7 changed files with 92 additions and 128 deletions.
diff --git a/README.md b/README.md
@@ -45,8 +45,85 @@ And run `webpack` via your preferred method.
 
 The `less-loader` requires [less](https://github.com/less/less.js) as [`peerDependency`](https://docs.npmjs.com/files/package.json#peerdependencies). Thus you are able to control the versions accurately.
 
+## Options
+
+### `lessOptions`
+
+Type: `Object`
+
+You can pass any Less specific options to the `less-loader` through the `lessOptions` property in the [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:
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.less$/,
+        use: [
+          {
+            loader: 'style-loader',
+          },
+          {
+            loader: 'css-loader',
+          },
+          {
+            loader: 'less-loader',
+            options: {
+              lessOptions: {
+                strictMath: true,
+                noIeCompat: true,
+              },
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### `sourceMap`
+
+Type: `Boolean`
+Default: depends on the `compiler.devtool` value
+
+By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. All values enable source map generation except `eval` and `false` value.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.less$/i,
+        use: [
+          'style-loader',
+          {
+            loader: 'css-loader',
+            options: {
+              sourceMap: true,
+            },
+          },
+          {
+            loader: 'less-loader',
+            options: {
+              sourceMap: true,
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
 ## Examples
 
+### Normal usage
+
 Chain the `less-loader` with the [`css-loader`](https://github.com/webpack-contrib/css-loader) and the [`style-loader`](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM.
 
 **webpack.config.js**
@@ -74,30 +151,33 @@ module.exports = {
 };
 ```
 
-You can pass any Less specific options to the `less-loader` through the `lessOptions` property in the [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:
+Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, [check their executable](https://github.com/less/less.js/blob/3.x/bin/lessc) and search for the dash-case option.
+
+### Source maps
+
+To enable sourcemaps for CSS, you'll need to pass the `sourceMap` property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in `devtool`.
 
 **webpack.config.js**
 
-```js
+```javascript
 module.exports = {
+  devtool: 'source-map', // any "source-map"-like devtool is possible
   module: {
     rules: [
       {
         test: /\.less$/,
         use: [
-          {
-            loader: 'style-loader',
-          },
+          'style-loader',
           {
             loader: 'css-loader',
+            options: {
+              sourceMap: true,
+            },
           },
           {
             loader: 'less-loader',
             options: {
-              lessOptions: {
-                strictMath: true,
-                noIeCompat: true,
-              },
+              sourceMap: true,
             },
           },
         ],
@@ -107,7 +187,7 @@ module.exports = {
 };
 ```
 
-Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, [check their executable](https://github.com/less/less.js/blob/3.x/bin/lessc) and search for the dash-case option.
+If you want to edit the original Less files inside Chrome, [there's a good blog post](https://medium.com/@toolmantim/getting-started-with-css-sourcemaps-and-in-browser-sass-editing-b4daab987fb0). The blog post is about Sass but it also works for Less.
 
 ### In production
 
@@ -220,45 +300,6 @@ There are two possibilities to extract a style sheet from the bundle:
 - [`extract-loader`](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)
 - [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin) (more complex, but works in all use-cases)
 
-### Source maps
-
-To enable CSS source maps, you'll need to pass the `sourceMap` option to the `less-loader` _and_ the `css-loader`. Your `webpack.config.js` should look like this:
-
-**webpack.config.js**
-
-```javascript
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.less$/,
-        use: [
-          {
-            loader: 'style-loader',
-          },
-          {
-            loader: 'css-loader',
-            options: {
-              sourceMap: true,
-            },
-          },
-          {
-            loader: 'less-loader',
-            options: {
-              sourceMap: true,
-            },
-          },
-        ],
-      },
-    ],
-  },
-};
-```
-
-Also checkout the [sourceMaps example](https://github.com/webpack-contrib/less-loader/tree/master/examples/sourceMaps).
-
-If you want to edit the original Less files inside Chrome, [there's a good blog post](https://medium.com/@toolmantim/getting-started-with-css-sourcemaps-and-in-browser-sass-editing-b4daab987fb0). The blog post is about Sass but it also works for Less.
-
 ### CSS modules gotcha
 
 There is a known problem with Less and [CSS modules](https://github.com/css-modules/css-modules) regarding relative file paths in `url(...)` statements. [See this issue for an explanation](https://github.com/webpack-contrib/less-loader/issues/109#issuecomment-253797335).

diff --git a/examples/sourceMaps/index.html b/examples/sourceMaps/index.html
diff --git a/examples/sourceMaps/main.less b/examples/sourceMaps/main.less
diff --git a/examples/sourceMaps/other.less b/examples/sourceMaps/other.less
diff --git a/examples/sourceMaps/package.json b/examples/sourceMaps/package.json
diff --git a/examples/sourceMaps/webpack.config.js b/examples/sourceMaps/webpack.config.js
diff --git a/src/options.json b/src/options.json
@@ -3,15 +3,8 @@
   "properties": {
     "lessOptions": {
       "description": "Options to pass through to `less`. (https://github.com/webpack-contrib/less-loader#examples).",
-      "anyOf": [
-        {
-          "type": "object",
-          "additionalProperties": true
-        },
-        {
-          "instanceof": "Function"
-        }
-      ]
+      "type": "object",
+      "additionalProperties": true
     },
     "sourceMap": {
       "description": "Enables/Disables generation of source maps (https://github.com/webpack-contrib/less-loader#source-maps).",