[![npm][npm]][npm-url] [![node][node]][node-url] [![deps][deps]][deps-url] [![tests][tests]][tests-url] [![chat][chat]][chat-url]
A Less loader for webpack. Compiles Less to CSS.
This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.
To begin, you'll need to install less-loader:
$ npm install less-loader --save-dev
Then modify your webpack.config.js:
// webpack.config.js
module.exports = {
...
module: {
rules: [{
test: /\.less$/,
loader: 'less-loader' // compiles Less to CSS
}]
}
};
And run webpack via your preferred method.
The less-loader requires less as peerDependency. Thus you are able to control the versions accurately.
Chain the less-loader with the css-loader and the style-loader to immediately apply all styles to the DOM.
// webpack.config.js
module.exports = {
...
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
}]
}]
}
};
You can pass any Less specific options to the less-loader via loader options. See the Less documentation 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
module.exports = {
...
module: {
rules: [{
test: /\.less$/,
use: [{
loader: 'style-loader'
}, {
loader: 'css-loader'
}, {
loader: 'less-loader', options: {
strictMath: true,
noIeCompat: true
}
}]
}]
}
};
Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, check their executable and search for the dash-case option.
Usually, it's recommended to extract the style sheets into a dedicated file in production using the MiniCssExtractPlugin. This way your styles are not dependent on JavaScript.
Starting with less-loader 4, you can now choose between Less' builtin resolver and webpack's resolver. By default, webpack's resolver is used.
webpack provides an advanced mechanism to resolve files. The less-loader applies a Less plugin that passes all queries to the webpack resolver. Thus you can import your Less modules from node_modules. Just prepend them with a ~ which tells webpack to look up the modules.
@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";
Using webpack's resolver, you can import any file type. You just need a loader that exports valid Less code. Often, you will also want to set the issuer condition to ensure that this rule is only applied on imports originating from Less files:
// webpack.config.js
module.exports = {
...
module: {
rules: [{
test: /\.js$/,
issuer: /\.less$/,
use: [{
loader: 'js-to-less-loader'
}]
}]
}
};
If you specify the paths option, the less-loader will not use webpack's resolver. Modules, that can't be resolved in the local folder, will be searched in the given paths. This is Less' default behavior. paths should be an array with absolute paths:
// webpack.config.js
module.exports = {
...
module: {
rules: [{
test: /\.less$/,
use: [{
loader: 'style-loader'
}, {
loader: 'css-loader'
}, {
loader: 'less-loader', options: {
paths: [
path.resolve(__dirname, 'node_modules')
]
}
}]
}]
}
};
In this case, all webpack features like importing non-Less files or aliasing won't work of course.
In order to use plugins, simply set the plugins option like this:
// webpack.config.js
const CleanCSSPlugin = require('less-plugin-clean-css');
module.exports = {
...
{
loader: 'less-loader', options: {
plugins: [
new CleanCSSPlugin({ advanced: true })
]
}
}]
...
};
Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or 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 might be visible. Thus it's often still better to have them as separate files in your final production build.
There are two possibilities to extract a style sheet from the bundle:
extract-loader (simpler, but specialized on the css-loader's output)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:
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.
If you want to edit the original Less files inside Chrome, there's a good blog post. The blog post is about Sass but it also works for Less.
There is a known problem with Less and CSS modules regarding relative file paths in url(...) statements. See this issue for an explanation.
Please take a moment to read our contributing guidelines if you haven't yet done so.
© JS Foundation and other contributors
Licensed under the Creative Commons Attribution License 4.0.
https://webpack.js.org/loaders/less-loader