webpack/less-loaderPublic

NotificationsYou must be signed in to change notification settings
Fork198
Star961

Compiles Less to CSS

License

MIT license

961 stars 198 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 468 Commits
.github/workflows		.github/workflows
.husky		.husky
src		src
test		test
.cspell.json		.cspell.json
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json

Repository files navigation

less-loader

A Less loader for webpack that compiles Less files into CSS.

Getting Started

To begin, you'll need to installless andless-loader:

npm install less less-loader --save-dev

yarn add -D less less-loader

pnpm add -D less less-loader

Then add the loader to yourwebpack configuration. For example:

webpack.config.js

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

Finally, runwebpack using the method you normally use (e.g., via CLI or an npm script).

Options

`lessOptions`

Type:

typelessOptions=import('less').options|((loaderContext:LoaderContext)=>import('less').options})

Default:{ relativeUrls: true }

You can pass any Less specific options to theless-loader through thelessOptions property in theloader options. See theLess 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 directly 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 Less options dynamically based on 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;constrelativePath=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:

typeadditionalData=|string|((content:string,loaderContext:LoaderContext)=>string);

Default:undefined

Prepends or AppendsLess code to the actual entry file.In this case, theless-loader will not override the source but justprepend 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;constrelativePath=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;constrelativePath=path.relative(rootContext,resourcePath);if(relativePath==="styles/foo.less"){return`@value: 100px;${content}`;}return`@value: 200px;${content}`;},},},],},],},};

`sourceMap`

Type:

typesourceMap=boolean;

Default: depends on thecompiler.devtool value

By default generation of source maps depends on thedevtool option.All values enable source map generation excepteval andfalse 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:

typewebpackImporter=boolean|"only";

Default:true

Enables or disables the defaultwebpack importer.

This can improve performance in some cases. Use it with caution because aliases and@import fromnode_modules 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:

typeimplementation=object|string;

less-loader compatible with both Less 3 and 4 versions

The specialimplementation option determines which implementation of Less to use. Overrides the locally installedpeerDependency version ofless.

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

`object`

Example using a Less instance:

webpack.config.js

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

`string`

Example using a resolved Less module path:

webpack.config.js

module.exports={module:{rules:[{test:/\.less$/i,use:["style-loader","css-loader",{loader:"less-loader",options:{implementation:require.resolve("less"),},},],},],},};

`lessLogAsWarnOrErr`

Type:

typelessLogAsWarnOrErr=boolean;

Default:false

Less warnings and errors will be treated as webpack warnings and errors, instead of being logged silently.

warning.less

div {&:extend(.body1);}

IflessLogAsWarnOrErr is set tofalse it will be just a log and webpack will compile successfully, but if you set this option totrue webpack will compile fail with a warning(or error), and can break the build if configured accordingly.

webpack.config.js

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

Examples

Normal usage

Chain theless-loader withcss-loader andstyle-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 thesourceMap property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set indevtool.

webpack.config.js

module.exports={devtool:"source-map",// any "source-map"-like devtool is possiblemodule:{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 theMiniCssExtractPlugin. This way your styles are not dependent on JavaScript, improving performance and cacheability.

Imports

First we try to use built-inless resolve logic, thenwebpack resolve logic.

Webpack Resolver

webpack provides anadvanced mechanism to resolve files.less-loader applies a Less plugin that passes all queries to the webpack resolver ifless could not resolve@import.Thus you can import your Less modules fromnode_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 insidenode_modules.

Default resolver options can be modified byresolve.byDependency:

webpack.config.js

module.exports={devtool:"source-map",// any "source-map"-like devtool is possiblemodule:{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"],},},},};

Less Resolver

If you specify thepaths option, modules will be searched in the givenpaths. This isless 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 useLess plugins, simply set theplugins option like this:

webpack.config.js

constCleanCSSPlugin=require('less-plugin-clean-css');module.exports={  ...{loader:'less-loader',options:{lessOptions:{plugins:[newCleanCSSPlugin({advanced:true}),],},},},  ...};

Note

Access to theloader context inside a custom plugin can be done using thepluginManager.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 orHot 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 aFOUC 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 when using Less withCSS modules regarding relative file paths inurl(...) 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.

CONTRIBUTING