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

A Less loader for webpack. Compiles Less to CSS.

Getting Started

To begin, you'll need to install less and less-loader:

$ npm install less less-loader --save-dev

Then add the loader to your webpack config. For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        loader: [
          // compiles Less to CSS
          "style-loader",
          "css-loader",
          "less-loader",
        ],
      },
    ],
  },
};

And run webpack via your preferred method.

Options

Name	Type	Default	Description
lessOptions	{Object|Function}	{ relativeUrls: true }	Options for Less.
additionalData	{String|Function}	undefined	Prepends/Appends Less code to the actual entry file.
sourceMap	{Boolean}	compiler.devtool	Enables/Disables generation of source maps.
webpackImporter	{Boolean}	true	Enables/Disables the default Webpack importer.
implementation	{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$/i,
        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$/i,
        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"],
                };
              },
            },
          },
        ],
      },
    ],
  },
};

additionalData

Type: String|Function Default: undefined

Prepends Less code before the actual entry file. In this case, the less-loader will not override the source but just prepend the entry's content.

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$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "less-loader",
            options: {
              additionalData: `@env: ${process.env.NODE_ENV};`,
            },
          },
        ],
      },
    ],
  },
};

Function

Sync

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "less-loader",
            options: {
              additionalData: (content, 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;" + content;
                }

                return "@value: 200px;" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

Async

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "less-loader",
            options: {
              additionalData: async (content, 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;" + content;
                }

                return "@value: 200px;" + content;
              },
            },
          },
        ],
      },
    ],
  },
};

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

webpackImporter

Type: Boolean Default: true

Enables/Disables the default webpack importer.

This can improve performance in some cases. Use it with caution because aliases and @import at-rules starting with ~ will not work.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "less-loader",
            options: {
              webpackImporter: false,
            },
          },
        ],
      },
    ],
  },
};

implementation

Type: Object

⚠ less-loader compatible with Less 3 and 4 versions

The special implementation option determines which implementation of Less to use. Overrides the locally installed peerDependency version of less.

This option is only really useful for downstream tooling authors to ease the Less 3-to-4 transition.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        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$/i,
        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$/i,
        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

First we try to use built-in less resolve logic, then webpack resolve logic (aliases and ~).

Webpack Resolver

webpack provides an advanced mechanism to resolve files. less-loader applies a Less plugin that passes all queries to the webpack resolver if less could not resolve @import. Thus you can import your Less modules from node_modules.

@import "bootstrap/less/bootstrap";

Using ~ is deprecated and can be removed from your code (we recommend it), but we still support it for historical reasons. Why you can removed it? The loader will first try to resolve @import as relative, if it cannot be resolved, the loader will try to resolve @import inside node_modules. Just prepend them with a ~ which tells webpack to look up the modules.

@import "~bootstrap/less/bootstrap";

Default resolver options can be modified by resolve.byDependency:

webpack.config.js

module.exports = {
  devtool: "source-map", // any "source-map"-like devtool is possible
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: ["style-loader", "css-loader", "less-loader"],
      },
    ],
  },
  resolve: {
    byDependency: {
      // More options can be found here https://webpack.js.org/configuration/resolve/
      less: {
        mainFiles: ["custom"],
      },
    },
  },
};

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";

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$/i,
        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 }),
          ],
        },
      },
    },
  ...
};

ℹ️ Access to the loader context inside the custom plugin can be done using the pluginManager.webpackLoaderContext property.

module.exports = {
  install: function (less, pluginManager, functions) {
    functions.add("pi", function () {
      // Loader context is available in `pluginManager.webpackLoaderContext`

      return Math.PI;
    });
  },
};

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.

CONTRIBUTING

License

MIT

Changelog

9.0.0 (2021-05-13)

⚠ BREAKING CHANGES

• minimum supported Node.js version is 12.13.0