esbuild-plugin-less

1.3.38 verified Mon Apr 27 auth: no javascript

esbuild plugin for compiling LESS files to CSS. Current stable version v1.3.38 (released 2026-04-11), updated regularly via semantic-release. Supports all LESS.js features, CSS Modules via .module.less naming convention, watch mode, custom file filters, and inline mode. Written in TypeScript with bundled types. Requires esbuild >=0.14.0 <0.29 as a peer dependency. Differentiator: minimal configuration, first-class CSS Modules support, and active maintenance.

Common errors

error Error: [plugin: less-loader] Cannot find module 'less' ↓

cause The 'less' package is not installed.

fix

Run npm install less --save-dev (or yarn/pnpm equivalent). This package uses less as a transitive dependency.

error Error: [plugin: less-loader] Options.math was set to 'parens-division' which is deprecated; use 'always' or 'strict'. ↓

cause Deprecated LESS math option value used.

fix

Change math: 'parens-division' to math: 'always' or math: 'strict'.

error TypeError: (0 , esbuild_plugin_less.lessLoader) is not a function ↓

cause Using default import instead of named import.

fix

Use import { lessLoader } from 'esbuild-plugin-less' instead of import lessLoader from 'esbuild-plugin-less'.

Warnings

gotcha CSS Modules only work with files named *.module.less – other .less files are treated as global styles. ↓

fix Rename your LESS file to include .module.less (e.g., styles.module.less) to enable CSS Modules scoping.

deprecated The `javascriptEnabled` option in LESS is a security risk and its support may be removed in future versions of less-loader. ↓

fix Avoid using `javascriptEnabled: true` – prefer static LESS variables and mixins instead of inline JavaScript.

breaking In v1.0.0, the plugin API changed from `lessPlugin()` to `lessLoader()`. Old imports will fail. ↓

fix Replace `lessPlugin` with `lessLoader` in both imports and usage.

gotcha The `inline` option when set to `true` causes the raw LESS source to be imported as a string instead of compiled CSS, which may break CSS injection. ↓

fix Ensure you are using the correct mode: `inline: false` (default) for compiled CSS output.

Install

npm install esbuild-plugin-less

yarn add esbuild-plugin-less

pnpm add esbuild-plugin-less

Imports

lessLoader
wrong
```
const lessLoader = require('esbuild-plugin-less')
```
correct
```
import { lessLoader } from 'esbuild-plugin-less'
```
Named import is the only correct pattern; package is ESM with CommonJS compat, but require() may break in strict ESM contexts.
LessLoaderOptions
wrong
```
import { LessLoaderOptions } from 'esbuild-plugin-less'
```
correct
```
import type { LessLoaderOptions } from 'esbuild-plugin-less'
```
It is a type-only export; use `import type` to avoid runtime errors in bundlers that do not elide types.
default export
wrong
```
const lessLoader = require('esbuild-plugin-less');
```
correct
```
import lessLoader from 'esbuild-plugin-less'
```
There is no default export; only named exports. This import will fail at runtime.

Quickstart

Shows basic usage of lessLoader plugin with LESS options (math always, global variables) in an esbuild build script.

import { build } from 'esbuild';
import { lessLoader } from 'esbuild-plugin-less';

build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    lessLoader({
      math: 'always',
      globalVars: {
        primaryColor: '#ff0000',
      },
    }),
  ],
  loader: {
    '.ts': 'ts',
  },
}).catch(() => process.exit(1));