less-loader
A Less loader for webpack. Compiles Less to CSS.
Getting Started
To begin, you'll need to install less-loader:
$ npm install less-loader --save-dev
Then add the loader to your webpack config. For example:
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.
Examples
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.
In production
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.
Imports
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 resolver
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";
Non-Less imports
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',
},
],
},
],
},
};
Less resolver
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.
Plugins
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 })
]
}
}]
...
};
Extracting style sheets
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)- MiniCssExtractPlugin
(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
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.
CSS modules gotcha
There is a known problem with Less and
CSS modules regarding relative
file paths in url(...) statements.
See this issue for an explanation.
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.