Skip to content

Commit 79445fa

Browse files
jhnnsjhnns
authored
Merge pull request #151 from webpack-contrib/update/readme
Update README
2 parents 72ba408 + 2d78a36 commit 79445fa

File tree

1 file changed

+88
-113
lines changed

1 file changed

+88
-113
lines changed

‎README.md‎

Lines changed: 88 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
<img width="200" height="200"
1313
src="https://webpack.js.org/assets/icon-square-big.svg">
1414
</a>
15-
<h1>LESS Loader</h1>
15+
<h1>less-loader</h1>
16+
<p>Compiles Less to CSS.<br>Use the <a href="https://github.com/webpack-contrib/css-loader">css-loader</a> or the <a href="https://github.com/webpack-contrib/raw-loader">raw-loader</a> to turn it into a JS module and the <a href="https://github.com/webpack-contrib/extract-text-webpack-plugin">ExtractTextPlugin</a> to extract it into a separate file.<p>
1617
</div>
1718

1819
<h2 align="center">Install</h2>
@@ -21,144 +22,118 @@
2122
npm install --save-dev less-loader less
2223
```
2324

24-
<h2 align="center">Usage</h2>
25+
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.
2526

26-
Use [`less-loader`](https://github.com/webpack/less-loader) in tandem with [css-loader](https://github.com/webpack/css-loader) & [style-loader](https://github.com/webpack/style-loader) to add LESS support for webpack.
27+
<h2 align="center">Examples</h2>
2728

28-
Use the loader either via your webpack config, CLI or inline.
29+
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.
2930

30-
### Via webpack config (recommended)
31-
32-
**webpack.config.js**
3331
```js
32+
// webpack.config.js
3433
module.exports = {
35-
module: {
36-
rules: [
37-
{
38-
test: /\.less$/,
39-
use: [
40-
'style-loader',
41-
{ loader: 'css-loader', options: { importLoaders: 1 } },
42-
'less-loader'
43-
]
44-
}
45-
]
46-
}
47-
}
48-
```
49-
50-
**In your application**
51-
```js
52-
import css from 'file.less';
53-
```
54-
55-
### CLI
56-
57-
```bash
58-
webpack --module-bind 'less=style-loader!css-loader!less-loader'
59-
```
60-
61-
**In your application**
62-
```js
63-
import css from 'file.less';
64-
```
65-
66-
### Inline
67-
68-
**In your application**
69-
```js
70-
import css from 'style-loader!css-loader!less-loader!./file.less';
34+
...
35+
module: {
36+
rules: [{
37+
test: /\.less$/,
38+
use: [{
39+
loader: "style-loader" // creates style nodes from JS strings
40+
}, {
41+
loader: "css-loader" // translates CSS into CommonJS
42+
}, {
43+
loader: "less-loader" // compiles Less to CSS
44+
}]
45+
}]
46+
}
47+
};
7148
```
7249

7350
<h2 align="center">Options</h2>
7451

75-
You can pass any LESS specific options to less-loader via loader options or query parameters.
76-
77-
See the [LESS documentation](http://lesscss.org/usage/#command-line-usage-options) for all available options. LESS translates dash-case to camelCase. Certain options which take values (e.g. `lessc --modify-var="a=b"`) are better handled with the [JSON Syntax](http://webpack.github.io/docs/using-loaders.html#query-parameters)
52+
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.
7853

7954
```js
80-
{
81-
test: /\.less$/,
82-
use: [
83-
'style-loader',
84-
{ loader: 'css-loader', options: { importLoaders: 1 } },
85-
{ loader: 'less-loader', options: { strictMath: true, noIeCompat: true } }
86-
]
87-
}
55+
// webpack.config.js
56+
module.exports = {
57+
...
58+
module: {
59+
rules: [{
60+
test: /\.less$/,
61+
use: [{
62+
loader: "style-loader"
63+
}, {
64+
loader: "css-loader"
65+
}, {
66+
loader: "less-loader", options: {
67+
strictMath: true,
68+
noIeCompat: true
69+
}
70+
}]
71+
}]
72+
}
73+
};
8874
```
8975

9076
### Plugins
9177

92-
In order to use [plugins](http://lesscss.org/usage/#plugins), simply set
93-
the `options.lessPlugins`-option on your `webpack.config.js`.
78+
In order to use [plugins](http://lesscss.org/usage/#plugins), simply set the `lessPlugins` option like this:
9479

9580
```js
96-
const CleanCSSPlugin = require('less-plugin-clean-css');
97-
98-
{
99-
test: /\.less$/,
100-
use: [
101-
'style-loader',
102-
{ loader: 'css-loader', options: { importLoaders: 1 } },
103-
{
104-
loader: 'less-loader',
105-
options: { lessPlugins: [ new CleanCSSPlugin({ advanced: true }) ] }
106-
}
107-
}
81+
// webpack.config.js
82+
const CleanCSSPlugin = require("less-plugin-clean-css");
83+
84+
module.exports = {
85+
...
86+
{
87+
loader: "less-loader", options: {
88+
lessPlugins: [
89+
new CleanCSSPlugin({ advanced: true })
90+
]
91+
}
92+
}]
93+
...
94+
};
10895
```
10996

11097
### Imports
11198

112-
webpack provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/). The less-loader stubs less' `fileLoader` and 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)
99+
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).
113100

114101
```css
115102
@import "~bootstrap/less/bootstrap";
116103
```
117104

118105
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";`
119106

120-
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/less-loader/issues/109#issuecomment-253797335).
107+
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).
121108

122-
### Sourcemaps
109+
### Source maps
123110

124-
Because of browser limitations, sourcemaps are only available in conjunction with the [extract-text-webpack-plugin](https://github.com/webpack/extract-text-webpack-plugin). Use that plugin to extract the CSS code from the generated JS bundle into a separate file (which improves performance because JS and CSS are loaded in parallel).
125-
126-
**webpack.config.js**
127-
```js
128-
const ExtractTextPlugin = require('extract-text-webpack-plugin');
111+
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:
129112

113+
```javascript
130114
module.exports = {
131-
// must be 'source-map' or 'inline-source-map'
132-
devtool: 'source-map',
133-
module: {
134-
rules: [
135-
{
136-
test: /\.less$/,
137-
use: ExtractTextPlugin.extract(
138-
fallbackLoader: 'style-loader',
139-
loaders: [
140-
// activate source maps via loader query
141-
{
142-
loader: 'css-loader',
143-
options: { sourceMap: true, importLoaders: 1 }
144-
},
145-
{
146-
loader: 'less-loader',
147-
options: { sourceMap: true }
148-
}
149-
]
150-
)
151-
}
152-
]
153-
},
154-
plugins: [
155-
// extract CSS into separate file
156-
new ExtractTextPlugin('app.bundle.css')
157-
]
158-
}
115+
...
116+
devtool: "source-map", // any "source-map"-like devtool is possible
117+
module: {
118+
rules: [{
119+
test: /\.less$/,
120+
use: [{
121+
loader: "style-loader"
122+
}, {
123+
loader: "css-loader", options: {
124+
sourceMap: true
125+
}
126+
}, {
127+
loader: "less-loader", options: {
128+
sourceMap: true
129+
}
130+
}]
131+
}]
132+
}
133+
};
159134
```
160135

161-
If you want to view the original LESS files inside Chrome and even edit it, [there's a good blog post](https://medium.com/@toolmantim/getting-started-with-css-sourcemaps-and-in-browser-sass-editing-b4daab987fb0). Checkout [test/sourceMap](https://github.com/webpack/less-loader/tree/master/test) for a running example. Make sure to serve the content with an HTTP server.
136+
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.
162137

163138
<h2 align="center">Contributing</h2>
164139

@@ -187,14 +162,14 @@ The tests are basically just comparing the generated css with a reference css-fi
187162
[node]: https://img.shields.io/node/v/less-loader.svg
188163
[node-url]: https://nodejs.org
189164

190-
[deps]: https://david-dm.org/webpack/less-loader.svg
191-
[deps-url]: https://david-dm.org/webpack/less-loader
165+
[deps]: https://david-dm.org/webpack-contrib/less-loader.svg
166+
[deps-url]: https://david-dm.org/webpack-contrib/less-loader
192167

193-
[tests]: http://img.shields.io/travis/webpack/less-loader.svg
194-
[tests-url]: https://travis-ci.org/webpack/less-loader
168+
[tests]: http://img.shields.io/travis/webpack-contrib/less-loader.svg
169+
[tests-url]: https://travis-ci.org/webpack-contrib/less-loader
195170

196-
[cover]: https://coveralls.io/repos/github/webpack/less-loader/badge.svg
197-
[cover-url]: https://coveralls.io/github/webpack/less-loader
171+
[cover]: https://coveralls.io/repos/github/webpack-contrib/less-loader/badge.svg
172+
[cover-url]: https://coveralls.io/github/webpack-contrib/less-loader
198173

199-
[chat]: https://badges.gitter.im/webpack/webpack.svg
200-
[chat-url]: https://gitter.im/webpack/webpack
174+
[chat]: https://badges.gitter.im/webpack-contrib/webpack.svg
175+
[chat-url]: https://gitter.im/webpack-contrib/webpack

0 commit comments

Comments
 (0)