less-loader

What is less-loader?

The less-loader npm package is a loader for webpack that allows you to preprocess Less files into CSS. This enables developers to write styles in Less, a dynamic preprocessor style language that extends CSS with dynamic behavior such as variables, mixins, operations, and functions, and compile them into native CSS files that can be loaded into a web page.

What are less-loader's main functionalities?

Compiling Less to CSS

This feature allows you to compile Less files into CSS. The code sample shows how to configure webpack to use less-loader along with css-loader and style-loader to process `.less` files.

module.exports = {
  module: {
    rules: [{
      test: /\.less$/,
      use: [
        'style-loader',
        'css-loader',
        'less-loader'
      ]
    }]
  }
};

Importing Other Less or CSS Files

less-loader supports importing other Less or CSS files within a Less file. This feature enables code reusability and modularization. The code sample demonstrates importing a 'library' file and using a variable from it.

@import 'library';

.body {
  color: @baseColor;
}

Customizing Less Options

This feature allows the customization of Less compiler options through less-loader. The code sample demonstrates how to enable strict math and disable IE compatibility mode by configuring less-loader options in webpack.

module.exports = {
  module: {
    rules: [{
      test: /\.less$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'less-loader',
          options: {
            lessOptions: {
              strictMath: true,
              noIeCompat: true
            }
          }
        }
      ]
    }]
  }
};

Other packages similar to less-loader

sass-loader

sass-loader is similar to less-loader but for compiling Sass/SCSS files into CSS. While less-loader focuses on Less files, sass-loader provides functionality for Sass, another popular CSS preprocessor language. Both loaders serve a similar purpose of integrating CSS preprocessing into webpack's build process.

stylus-loader

stylus-loader is designed for processing Stylus files into CSS, similar to how less-loader works with Less files. Stylus is another CSS preprocessor that offers syntax and features comparable to Less and Sass. The choice between less-loader, sass-loader, and stylus-loader typically depends on the specific preprocessor language a project uses.

postcss-loader

postcss-loader is a loader that allows you to use PostCSS, a tool for transforming CSS with JavaScript plugins. Unlike less-loader which is specific to Less, postcss-loader is more flexible and can be used to apply a wide range of transformations and optimizations to CSS files, making it a powerful tool in a developer's workflow.

README

less-loader

Compiles Less to CSS.
Use the css-loader or the raw-loader to turn it into a JS module and the ExtractTextPlugin to extract it into a separate file.

Install

npm install --save-dev less-loader less

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
                }
            }]
        }]
    }
};

In production

Usually, it's recommended to extract the style sheets into a dedicated file in production using the ExtractTextPlugin. This way your styles are not dependent on JavaScript:

const ExtractTextPlugin = require("extract-text-webpack-plugin");

const extractLess = new ExtractTextPlugin({
    filename: "[name].[contenthash].css",
    disable: process.env.NODE_ENV === "development"
});

module.exports = {
    ...
    module: {
        rules: [{
            test: /\.less$/,
            loader: extractLess.extract({
                use: [{
                    loader: "css-loader"
                }, {
                    loader: "less-loader"
                }],
                // use style-loader in development
                fallback: "style-loader"
            })
        }]
    },
    plugins: [
        extractLess
    ]
};

Usage

Imports

webpack provides an advanced mechanism to resolve files. 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.

@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, relative file paths do not work as expected. Please see this issue for the explanation.

Plugins

In order to use plugins, simply set the lessPlugins option like this:

// webpack.config.js
const CleanCSSPlugin = require("less-plugin-clean-css");

module.exports = {
    ...
            {
                loader: "less-loader", options: {
                    lessPlugins: [
                        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)
• extract-text-webpack-plugin (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:

module.exports = {
    ...
    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 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.

Contributing

Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling npm test.

The tests are basically just comparing the generated css with a reference css-file located under test/css. You can easily generate a reference css-file by calling node test/helpers/generateCss.js <less-file-without-less-extension>. It passes the less-file to less and writes the output to the test/css-folder.

Maintainer

Johannes Ewald