A Less loader for webpack that compiles Less files into CSS.
Getting Started
To begin, you'll need to install less and less-loader:
npm install less less-loader --save-dev
or
yarn add -D less less-loader
or
pnpm add -D less less-loader
Then add the loader to your webpack configuration. For example:
webpack.config.js
module.exports = { module: { rules: [ { test: /\.less$/i, // Uses the built-in CSS support of webpack, i.e. `.module.less` files // are treated as CSS modules, other files are treated as plain CSS type: "css/auto", // Compiles Less to CSS use: ["less-loader"], }, ], }, experiments: { // Enables the built-in CSS support of webpack css: true, },};
type lessOptions = import('less').options | ((loaderContext: LoaderContext) => import('less').options})
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:
Prepends or Appends Less code to 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.
Less warnings and errors will be treated as webpack warnings and errors, instead of being logged silently.
warning.less
div { &:extend(.body1);}
If lessLogAsWarnOrErr is set to false it will be just a log and webpack will compile successfully, but if you leave the default value (or set this option to true) webpack will compile fail with a warning(or error), and can break the build if configured accordingly.
Set the module type to css/auto and enable experiments.css to let webpack handle the generated CSS with its built-in CSS support, without any extra loaders or plugins.
webpack.config.js
module.exports = { module: { rules: [ { test: /\.less$/i, type: "css/auto", // Handles the generated CSS using the built-in CSS support of webpack use: ["less-loader"], // Compiles Less to CSS }, ], }, experiments: { css: true, },};
The css/auto module type treats *.module.less files as CSS modules and any other file as plain CSS.
Use type: "css" to always treat the file as plain CSS, or type: "css/module" to always treat it as a CSS module.
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.
Using css-loader and style-loader
The built-in CSS support of webpack is not mandatory, you can still chain the less-loader with css-loader and style-loader to immediately apply all styles to the DOM.
Note that in this case the type and experiments.css options should not be set for this rule, and options like sourceMap have to be enabled for the css-loader too.
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.
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
The built-in CSS support of webpack always extracts style sheets into dedicated files, so your styles are not dependent on JavaScript, which improves performance and cacheability.
The name of the generated files can be configured using the output.cssFilename and output.cssChunkFilename options.
When you chain the loader with css-loader and style-loader instead, it's recommended to extract the style sheets into a dedicated file in production using the MiniCssExtractPlugin.
Imports
First we try to use built-in less resolve logic, then webpack resolve logic.
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 ~ prefix (e.g., @import "~bootstrap/less/bootstrap";) 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.
module.exports = { devtool: "source-map", // any "source-map"-like devtool is possible module: { rules: [ { test: /\.less$/i, type: "css/auto", use: ["less-loader"], }, ], }, experiments: { css: true, }, resolve: { byDependency: { // More options can be found here https://webpack.js.org/configuration/resolve/ less: { mainFiles: ["custom"], }, }, },};
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:
Access to the loader context inside a custom plugin can be done using the pluginManager.webpackLoaderContext property.
module.exports = { install(less, pluginManager, functions) { functions.add( "pi", () => // Loader context is available in `pluginManager.webpackLoaderContext` 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(HMR) 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.
The built-in CSS support of webpack does this out of the box: every entry point and chunk gets its own style sheet, no extra plugin required.
When you chain the loader with the css-loader instead, use the MiniCssExtractPlugin to extract a style sheet from the bundle.
CSS modules
With the built-in CSS support of webpack, *.module.less files are treated as CSS modules when the module type is css/auto, and all files are treated as CSS modules when the module type is css/module:
import * as styles from "./style.module.less";document.body.className = styles.box;
There is a known problem when using Less with CSS modules regarding relative file paths in url(...) statements.
See this issue for an explanation.
Contributing
We welcome all contributions!
If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.