From cdb611f85c2c5c112e1e3597e4c0486d28bad01b Mon Sep 17 00:00:00 2001 From: Ryan Clark Date: Mon, 16 Mar 2020 15:37:04 +0000 Subject: [PATCH] chore: update README with examples, change lessOptions to only allow objects (#324) --- README.md | 139 +++++++++++++++++--------- examples/sourceMaps/index.html | 9 -- examples/sourceMaps/main.less | 6 -- examples/sourceMaps/other.less | 3 - examples/sourceMaps/package.json | 19 ---- examples/sourceMaps/webpack.config.js | 33 ------ src/options.json | 11 +- 7 files changed, 92 insertions(+), 128 deletions(-) delete mode 100644 examples/sourceMaps/index.html delete mode 100644 examples/sourceMaps/main.less delete mode 100644 examples/sourceMaps/other.less delete mode 100644 examples/sourceMaps/package.json delete mode 100644 examples/sourceMaps/webpack.config.js diff --git a/README.md b/README.md index 70266f30..d470fda0 100644 --- 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 deleted file mode 100644 index 0d7009d8..00000000 --- a/examples/sourceMaps/index.html +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - -
- - diff --git a/examples/sourceMaps/main.less b/examples/sourceMaps/main.less deleted file mode 100644 index 16c390fd..00000000 --- a/examples/sourceMaps/main.less +++ /dev/null @@ -1,6 +0,0 @@ -@import "./other.less"; - -.box:extend(.hotpink) { - width: 200px; - height: 200px; -} diff --git a/examples/sourceMaps/other.less b/examples/sourceMaps/other.less deleted file mode 100644 index 9cf35cd0..00000000 --- a/examples/sourceMaps/other.less +++ /dev/null @@ -1,3 +0,0 @@ -.hotpink { - background: hotpink; -} diff --git a/examples/sourceMaps/package.json b/examples/sourceMaps/package.json deleted file mode 100644 index 47755b76..00000000 --- a/examples/sourceMaps/package.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "name": "source-maps-example", - "version": "1.0.0", - "description": "", - "main": "index.js", - "scripts": { - "start": "webpack-dev-server", - "test": "echo \"Error: no test specified\" && exit 1" - }, - "author": "", - "license": "ISC", - "devDependencies": { - "css-loader": "^0.27.3", - "style-loader": "^0.14.1", - "less-loader": "^4.0.0", - "webpack": "^2.2.1", - "webpack-dev-server": "^2.4.2" - } -} diff --git a/examples/sourceMaps/webpack.config.js b/examples/sourceMaps/webpack.config.js deleted file mode 100644 index 0edddd31..00000000 --- a/examples/sourceMaps/webpack.config.js +++ /dev/null @@ -1,33 +0,0 @@ -module.exports = { - mode: 'development', - entry: require.resolve('./main.less'), - output: { - filename: 'bundle.js', - }, - devtool: 'eval', - module: { - rules: [ - { - test: /\.less$/, - use: [ - 'style-loader', - { - loader: 'css-loader', - options: { - sourceMap: true, - }, - }, - { - loader: require.resolve('../../dist'), - options: { - sourceMap: true, - }, - }, - ], - }, - ], - }, - devServer: { - inline: true, - }, -}; diff --git a/src/options.json b/src/options.json index b4353b37..135e10d9 100644 --- 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).",