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',
},
],
},
};
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',
},
{
loader: 'css-loader',
},
{
loader: 'less-loader',
},
],
},
],
},
};
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:
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:
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:
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.
CONTRIBUTING
License
MIT