{"id":13430054,"url":"https://github.com/webpack-contrib/less-loader","last_synced_at":"2025-05-12T13:24:48.668Z","repository":{"id":3161991,"uuid":"4192593","full_name":"webpack-contrib/less-loader","owner":"webpack-contrib","description":"Compiles Less to CSS","archived":false,"fork":false,"pushed_at":"2025-05-01T10:43:48.000Z","size":4041,"stargazers_count":960,"open_issues_count":2,"forks_count":197,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-08T00:06:27.923Z","etag":null,"topics":["less","webpack-loader"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"webpack"}},"created_at":"2012-05-01T13:42:53.000Z","updated_at":"2025-05-04T15:24:32.000Z","dependencies_parsed_at":"2024-02-20T14:55:47.007Z","dependency_job_id":"3d4281c9-933b-4657-8212-4d11a28fdf39","html_url":"https://github.com/webpack-contrib/less-loader","commit_stats":{"total_commits":403,"total_committers":57,"mean_commits":"7.0701754385964914","dds":0.7766749379652605,"last_synced_commit":"f3d3881e50f43150a9716eabe5c987c990462236"},"previous_names":["webpack/less-loader"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fless-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fless-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fless-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fless-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack-contrib","download_url":"https://codeload.github.com/webpack-contrib/less-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978668,"owners_count":21834910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["less","webpack-loader"],"created_at":"2024-07-31T02:00:49.593Z","updated_at":"2025-05-12T13:24:48.662Z","avatar_url":"https://github.com/webpack-contrib.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\" src=\"https://webpack.js.org/assets/icon-square-big.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![tests][tests]][tests-url]\n[![cover][cover]][cover-url]\n[![discussion][discussion]][discussion-url]\n[![size][size]][size-url]\n\n# less-loader\n\nA Less loader for webpack. Compiles Less to CSS.\n\n## Getting Started\n\nTo begin, you'll need to install `less` and `less-loader`:\n\n```console\nnpm install less less-loader --save-dev\n```\n\nor\n\n```console\nyarn add -D less less-loader\n```\n\nor\n\n```console\npnpm add -D less less-loader\n```\n\nThen add the loader to your `webpack` config. For example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          // compiles Less to CSS\n          \"style-loader\",\n          \"css-loader\",\n          \"less-loader\",\n        ],\n      },\n    ],\n  },\n};\n```\n\nAnd run `webpack` via your preferred method.\n\n## Options\n\n- **[`lessOptions`](#lessoptions)**\n- **[`additionalData`](#additionalData)**\n- **[`sourceMap`](#sourcemap)**\n- **[`webpackImporter`](#webpackimporter)**\n- **[`implementation`](#implementation)**\n- **[`lessLogAsWarnOrErr`](#lesslogaswarnorerr)**\n\n### `lessOptions`\n\nType:\n\n```ts\ntype lessOptions = import('less').options | ((loaderContext: LoaderContext) =\u003e import('less').options})\n```\n\nDefault: `{ relativeUrls: true }`\n\nYou can pass any Less specific options to the `less-loader` through the `lessOptions` property in the [loader options](https://webpack.js.org/configuration/module/#ruleoptions--rulequery). See the [Less documentation](http://lesscss.org/usage/#command-line-usage-options) for all available options in dash-case. Since we're passing these options to Less programmatically, you need to pass them in camelCase here:\n\n#### `object`\n\nUse an object to pass options through to Less.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          {\n            loader: \"style-loader\",\n          },\n          {\n            loader: \"css-loader\",\n          },\n          {\n            loader: \"less-loader\",\n            options: {\n              lessOptions: {\n                strictMath: true,\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `function`\n\nAllows setting the options passed through to Less based off of the loader context.\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              lessOptions: (loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.less\") {\n                  return {\n                    paths: [\"absolute/path/c\", \"absolute/path/d\"],\n                  };\n                }\n\n                return {\n                  paths: [\"absolute/path/a\", \"absolute/path/b\"],\n                };\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `additionalData`\n\nType:\n\n```ts\ntype additionalData =\n  | string\n  | ((content: string, loaderContext: LoaderContext) =\u003e string);\n```\n\nDefault: `undefined`\n\nPrepends/Appends `Less` code to the actual entry file.\nIn this case, the `less-loader` will not override the source but just **prepend** the entry's content.\n\nThis is especially useful when some of your Less variables depend on the environment:\n\n\u003e 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.\n\n#### `string`\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              additionalData: `@env: ${process.env.NODE_ENV};`,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `function`\n\n##### `Sync`\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              additionalData: (content, loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.less\") {\n                  return \"@value: 100px;\" + content;\n                }\n\n                return \"@value: 200px;\" + content;\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n##### `Async`\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              additionalData: async (content, loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.less\") {\n                  return \"@value: 100px;\" + content;\n                }\n\n                return \"@value: 200px;\" + content;\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `sourceMap`\n\nType:\n\n```ts\ntype sourceMap = boolean;\n```\n\nDefault: depends on the `compiler.devtool` value\n\nBy default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. All values enable source map generation except `eval` and `false` value.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          {\n            loader: \"css-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n          {\n            loader: \"less-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `webpackImporter`\n\nType:\n\n```ts\ntype webpackImporter = boolean | \"only\";\n```\n\nDefault: `true`\n\nEnables/Disables the default `webpack` importer.\n\nThis can improve performance in some cases. Use it with caution because aliases and `@import` from [`node_modules`](https://webpack.js.org/configuration/resolve/#resolvemodules) will not work.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              webpackImporter: false,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `implementation`\n\nType:\n\n```ts\ntype implementation = object | string;\n```\n\n\u003e less-loader compatible with Less 3 and 4 versions\n\nThe special `implementation` option determines which implementation of Less to use. Overrides the locally installed `peerDependency` version of `less`.\n\n**This option is only really useful for downstream tooling authors to ease the Less 3-to-4 transition.**\n\n#### `object`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              implementation: require(\"less\"),\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `string`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              implementation: require.resolve(\"less\"),\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `lessLogAsWarnOrErr`\n\nType:\n\n```ts\ntype lessLogAsWarnOrErr = boolean;\n```\n\nDefault: `false`\n\n`Less` warnings and errors will be webpack warnings and errors, not just logs.\n\n**warning.less**\n\n```less\ndiv {\n  \u0026:extend(.body1);\n}\n```\n\nIf `lessLogAsWarnOrErr` is set to `false` it will be just a log and webpack will compile successfully, but if you set this option to `true` webpack will compile fail with a warning.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"less-loader\",\n            options: {\n              lessLogAsWarnOrErr: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n## Examples\n\n### Normal usage\n\nChain the `less-loader` with the [`css-loader`](https://github.com/webpack-contrib/css-loader) and the [`style-loader`](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          {\n            loader: \"style-loader\", // creates style nodes from JS strings\n          },\n          {\n            loader: \"css-loader\", // translates CSS into CommonJS\n          },\n          {\n            loader: \"less-loader\", // compiles Less to CSS\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nUnfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, [check their executable](https://github.com/less/less.js/blob/3.x/bin/lessc) and search for the dash-case option.\n\n### Source maps\n\nTo 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`.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  devtool: \"source-map\", // any \"source-map\"-like devtool is possible\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          \"style-loader\",\n          {\n            loader: \"css-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n          {\n            loader: \"less-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\nIf you want to edit the original Less files inside Chrome, [there's a good blog post](https://medium.com/@toolmantim/getting-started-with-css-sourcemaps-and-in-browser-sass-editing-b4daab987fb0). The blog post is about Sass but it also works for Less.\n\n### In production\n\nUsually, it's recommended to extract the style sheets into a dedicated file in production using the [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin). This way your styles are not dependent on JavaScript.\n\n### Imports\n\nFirst we try to use built-in `less` resolve logic, then `webpack` resolve logic.\n\n#### Webpack Resolver\n\n`webpack` provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/).\n`less-loader` applies a Less plugin that passes all queries to the webpack resolver if `less` could not resolve `@import`.\nThus you can import your Less modules from `node_modules`.\n\n```css\n@import \"bootstrap/less/bootstrap\";\n```\n\nUsing `~` is deprecated and can be removed from your code (**we recommend it**), but we still support it for historical reasons.\nWhy 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`](https://webpack.js.org/configuration/resolve/#resolvemodules).\n\nDefault resolver options can be modified by [`resolve.byDependency`](https://webpack.js.org/configuration/resolve/#resolvebydependency):\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  devtool: \"source-map\", // any \"source-map\"-like devtool is possible\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\"style-loader\", \"css-loader\", \"less-loader\"],\n      },\n    ],\n  },\n  resolve: {\n    byDependency: {\n      // More options can be found here https://webpack.js.org/configuration/resolve/\n      less: {\n        mainFiles: [\"custom\"],\n      },\n    },\n  },\n};\n```\n\n#### Less Resolver\n\nIf 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:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.less$/i,\n        use: [\n          {\n            loader: \"style-loader\",\n          },\n          {\n            loader: \"css-loader\",\n          },\n          {\n            loader: \"less-loader\",\n            options: {\n              lessOptions: {\n                paths: [path.resolve(__dirname, \"node_modules\")],\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### Plugins\n\nIn order to use [plugins](http://lesscss.org/usage/#plugins), simply set the `plugins` option like this:\n\n**webpack.config.js**\n\n```js\nconst CleanCSSPlugin = require('less-plugin-clean-css');\n\nmodule.exports = {\n  ...\n    {\n      loader: 'less-loader',\n      options: {\n        lessOptions: {\n          plugins: [\n            new CleanCSSPlugin({ advanced: true }),\n          ],\n        },\n      },\n    },\n  ...\n};\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Access to the [loader context](https://webpack.js.org/api/loaders/#the-loader-context) inside the custom plugin can be done using the `pluginManager.webpackLoaderContext` property.\n\n```js\nmodule.exports = {\n  install: function (less, pluginManager, functions) {\n    functions.add(\"pi\", function () {\n      // Loader context is available in `pluginManager.webpackLoaderContext`\n\n      return Math.PI;\n    });\n  },\n};\n```\n\n### Extracting style sheets\n\nBundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or [hot module replacement](https://webpack.js.org/concepts/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](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) might be visible. Thus it's often still better to have them as separate files in your final production build.\n\nThere are two possibilities to extract a style sheet from the bundle:\n\n- [`extract-loader`](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)\n- [`MiniCssExtractPlugin`](https://github.com/webpack-contrib/mini-css-extract-plugin) (more complex, but works in all use-cases)\n\n### CSS modules gotcha\n\nThere is a known problem with Less and [CSS modules](https://github.com/css-modules/css-modules) regarding relative file paths in `url(...)` statements. [See this issue for an explanation](https://github.com/webpack-contrib/less-loader/issues/109#issuecomment-253797335).\n\n## Contributing\n\nPlease take a moment to read our contributing guidelines if you haven't yet done so.\n\n[CONTRIBUTING](./.github/CONTRIBUTING.md)\n\n## License\n\n[MIT](./LICENSE)\n\n[npm]: https://img.shields.io/npm/v/less-loader.svg\n[npm-url]: https://npmjs.com/package/less-loader\n[node]: https://img.shields.io/node/v/less-loader.svg\n[node-url]: https://nodejs.org\n[tests]: https://github.com/webpack-contrib/less-loader/workflows/less-loader/badge.svg\n[tests-url]: https://github.com/webpack-contrib/less-loader/actions\n[cover]: https://codecov.io/gh/webpack-contrib/less-loader/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/webpack-contrib/less-loader\n[discussion]: https://img.shields.io/github/discussions/webpack/webpack\n[discussion-url]: https://github.com/webpack/webpack/discussions\n[size]: https://packagephobia.now.sh/badge?p=less-loader\n[size-url]: https://packagephobia.now.sh/result?p=less-loader\n","funding_links":["https://opencollective.com/webpack"],"categories":["CSS","JavaScript","Plugins"],"sub_categories":["Rspack Loaders"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fless-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack-contrib%2Fless-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fless-loader/lists"}