Skip to content

Commit

Permalink
Merge pull request #151 from webpack-contrib/update/readme
Browse files Browse the repository at this point in the history 
Update README
  • Loading branch information
@jhnns
jhnns committed Mar 7, 2017
2 parents 72ba408 + 2d78a36 commit 79445fa
Showing 1 changed file with 88 additions and 113 deletions.
201 changes: 88 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
<img width="200" height="200"
src="https://webpack.js.org/assets/icon-square-big.svg">
</a>
<h1>LESS Loader</h1>
<h1>less-loader</h1>
<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>
</div>

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

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

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.
<h2 align="center">Examples</h2>

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

### Via webpack config (recommended)

**webpack.config.js**
```js
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
'less-loader'
]
}
]
}
}
```

**In your application**
```js
import css from 'file.less';
```

### CLI

```bash
webpack --module-bind 'less=style-loader!css-loader!less-loader'
```

**In your application**
```js
import css from 'file.less';
```

### Inline

**In your application**
```js
import css from 'style-loader!css-loader!less-loader!./file.less';
...
module: {
rules: [{
test: /\.less$/,
use: [{
loader: "style-loader" // creates style nodes from JS strings
}, {
loader: "css-loader" // translates CSS into CommonJS
}, {
loader: "less-loader" // compiles Less to CSS
}]
}]
}
};
```

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

You can pass any LESS specific options to less-loader via loader options or query parameters.

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)
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
{
test: /\.less$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
{ loader: 'less-loader', options: { strictMath: true, noIeCompat: true } }
]
}
// webpack.config.js
module.exports = {
...
module: {
rules: [{
test: /\.less$/,
use: [{
loader: "style-loader"
}, {
loader: "css-loader"
}, {
loader: "less-loader", options: {
strictMath: true,
noIeCompat: true
}
}]
}]
}
};
```

### Plugins

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

```js
const CleanCSSPlugin = require('less-plugin-clean-css');

{
test: /\.less$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
{
loader: 'less-loader',
options: { lessPlugins: [ new CleanCSSPlugin({ advanced: true }) ] }
}
}
// webpack.config.js
const CleanCSSPlugin = require("less-plugin-clean-css");

module.exports = {
...
{
loader: "less-loader", options: {
lessPlugins: [
new CleanCSSPlugin({ advanced: true })
]
}
}]
...
};
```

### Imports

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

### Sourcemaps
### Source maps

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).

**webpack.config.js**
```js
const ExtractTextPlugin = require('extract-text-webpack-plugin');
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:

```javascript
module.exports = {
// must be 'source-map' or 'inline-source-map'
devtool: 'source-map',
module: {
rules: [
{
test: /\.less$/,
use: ExtractTextPlugin.extract(
fallbackLoader: 'style-loader',
loaders: [
// activate source maps via loader query
{
loader: 'css-loader',
options: { sourceMap: true, importLoaders: 1 }
},
{
loader: 'less-loader',
options: { sourceMap: true }
}
]
)
}
]
},
plugins: [
// extract CSS into separate file
new ExtractTextPlugin('app.bundle.css')
]
}
...
devtool: "source-map", // any "source-map"-like devtool is possible
module: {
rules: [{
test: /\.less$/,
use: [{
loader: "style-loader"
}, {
loader: "css-loader", options: {
sourceMap: true
}
}, {
loader: "less-loader", options: {
sourceMap: true
}
}]
}]
}
};
```

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.
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.

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

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

[deps]: https://david-dm.org/webpack/less-loader.svg
[deps-url]: https://david-dm.org/webpack/less-loader
[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/less-loader.svg
[tests-url]: https://travis-ci.org/webpack/less-loader
[tests]: http://img.shields.io/travis/webpack-contrib/less-loader.svg
[tests-url]: https://travis-ci.org/webpack-contrib/less-loader

[cover]: https://coveralls.io/repos/github/webpack/less-loader/badge.svg
[cover-url]: https://coveralls.io/github/webpack/less-loader
[cover]: https://coveralls.io/repos/github/webpack-contrib/less-loader/badge.svg
[cover-url]: https://coveralls.io/github/webpack-contrib/less-loader

[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[chat]: https://badges.gitter.im/webpack-contrib/webpack.svg
[chat-url]: https://gitter.im/webpack-contrib/webpack

0 comments on commit 79445fa

Please sign in to comment.