{Object\|Function}
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.
Options
| Name | Type | Default | Description |
|---|---|---|---|
Name Type Default Description |
{Object\|Function} |
{ relativeUrls: true } |
Options for Less. |
Name Type Default Description
|
{String\|Function} |
undefined |
Prepends Less code before the actual entry file. |
Name Type Default Description
|
{String\|Function} |
undefined |
Prepends Less code after the actual entry file. |
Name Type Default Description
|
{Boolean} |
compiler.devtool |
Enables/Disables generation of source maps. |
Name Type Default Description
|
{Object} |
less |
Setup Less implementation to use. |
lessOptions
Type: Object|Function
Default: { relativeUrls: true }
You can pass any Less specific options to the less-loader through the lessOptions property in the 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:
Object
Use an object to pass options through to Less.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
{
loader: 'style-loader',
},
{
loader: 'css-loader',
},
{
loader: 'less-loader',
options: {
lessOptions: {
strictMath: true,
},
},
},
],
},
],
},
};Function
Allows setting the options passed through to Less based off of the loader context.
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
lessOptions: (loaderContext) => {
// More information about available properties https://webpack.js.org/api/loaders/
const { resourcePath, rootContext } = loaderContext;
const relativePath = path.relative(rootContext, resourcePath);
if (relativePath === 'styles/foo.less') {
return {
paths: ['absolute/path/c', 'absolute/path/d'],
};
}
return {
paths: ['absolute/path/a', 'absolute/path/b'],
};
},
},
},
],
},
],
},
};prependData
Type: String|Function
Default: undefined
Prepends Less code before the actual entry file.
This is especially useful when some of your Less variables depend on the environment:
ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Less entry files.
String
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
prependData: `@env: ${process.env.NODE_ENV};`,
},
},
],
},
],
},
};Function
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
prependData: (loaderContext) => {
// More information about available properties https://webpack.js.org/api/loaders/
const { resourcePath, rootContext } = loaderContext;
const relativePath = path.relative(rootContext, resourcePath);
if (relativePath === 'styles/foo.less') {
return '@value: 100px;';
}
return '@value: 200px;';
},
},
},
],
},
],
},
};appendData
Type: String|Function
Default: undefined
AppendData Less code after the actual entry file.
This can be useful when you need to rewrite some of your Less variables.:
ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Less entry files.
String
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
appendData: `@env: ${process.env.NODE_ENV};`,
},
},
],
},
],
},
};Function
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
appendData: (loaderContext) => {
// More information about available properties https://webpack.js.org/api/loaders/
const { resourcePath, rootContext } = loaderContext;
const relativePath = path.relative(rootContext, resourcePath);
if (relativePath === 'styles/foo.less') {
return '@value: 100px;';
}
return '@value: 200px;';
},
},
},
],
},
],
},
};sourceMap
Type: Boolean
Default: depends on the compiler.devtool value
By default generation of source maps depends on the devtool option. All values enable source map generation except eval and false value.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.less$/i,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
sourceMap: true,
},
},
{
loader: 'less-loader',
options: {
sourceMap: true,
},
},
],
},
],
},
};implementation
Type: Object
Default: less
⚠ less-loader compatible with Less version 3 only
The special implementation option determines which implementation of Less to use.
The implementation options either accepts less as a module.
This is useful if you want to use Less with a smaller version. Do not forget that then you must install your own version of Less.
For example, to use custom Less implementation, you'd pass:
module.exports = {
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
'css-loader',
{
loader: 'less-loader',
options: {
implementation: require('less'),
},
},
],
},
],
},
};Examples
Normal usage
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
},
],
},
],
},
};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.
Source maps
To enable sourcemaps for CSS, you'll need to pass the sourceMap property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in devtool.
webpack.config.js
module.exports = {
devtool: 'source-map', // any "source-map"-like devtool is possible
module: {
rules: [
{
test: /\.less$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
sourceMap: true,
},
},
{
loader: 'less-loader',
options: {
sourceMap: true,
},
},
],
},
],
},
};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.
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, modules 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: {
lessOptions: {
paths: [path.resolve(__dirname, 'node_modules')],
},
},
},
],
},
],
},
};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: {
lessOptions: {
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)
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.