LESS Plugin System

What Is a LESS Plugin?

A LESS plugin is a small JavaScript module that registers one or more custom functions (or visitors that transform the parsed syntax tree) with the LESS compiler. Once loaded via @plugin "name";, those custom functions become callable directly from your .less files, just like a built-in function.

Plugins are typically distributed as npm packages, popular examples include less-plugin-clean-css for minification and less-plugin-glob for glob-based imports, though you can also write a small, project-specific plugin for custom logic.

// my-plugin.js
registerFunction("double", function (n) {
  return new (require("less").tree.Dimension)(n.value * 2, n.unit);
});

// styles.less
@plugin "my-plugin";

.box {
  width: double(10px); // 20px

The exact plugin registration API varies by LESS version; consult the official plugin documentation for your installed version.

Loading a Plugin

@plugin "plugin-name";

• @plugin loads a JavaScript file (resolved like a Node module) that registers new functions or compiler behavior.
• Plugins run during compilation only, they add zero runtime JavaScript to your compiled CSS output.
• Common official and community plugins solve minification, globbing, and autoprefixing needs.
• Custom plugins require Node.js-based compilation, they cannot run inside the in-browser less.js runtime.

LESS Plugin System Cheatsheet

Common plugins and what problem each one solves.

When You Actually Need a Plugin

Most projects never need a custom LESS plugin, built-in functions, mixins, and guards cover the vast majority of real styling logic. Reach for a plugin only when you need genuinely custom computation that can't be expressed within LESS's existing feature set.

• Custom unit conversions specific to a domain (like a print layout's DPI-aware sizing).
• Integrating a project-specific naming or validation rule directly into the compile step.
• Extending @import behavior, like glob-based imports across many component files.

Using Community Plugins

For common needs like minification, prefer an established, well-maintained community plugin over writing a custom one, since these typically handle far more edge cases than a project-specific implementation would.

npm install -D less-plugin-clean-css

Then run: lessc --clean-css input.less output.min.css

Plugins vs. Post-Processing Tools

Some tasks (autoprefixing, further minification, linting) are often better handled by a dedicated post-processing tool like PostCSS run after LESS compilation, rather than a LESS plugin itself, especially in a build pipeline that already uses PostCSS for other purposes.

• Use a LESS plugin when the logic needs to run during LESS's own compilation step.
• Use a separate PostCSS step for concerns that operate purely on the final CSS output.
• Avoid duplicating the same responsibility (like autoprefixing) in both a LESS plugin and a PostCSS plugin.

Common Mistakes

• Writing a custom plugin for logic that a built-in function, mixin, or guard could already express.
• Assuming a custom plugin will work with the in-browser less.js runtime; plugins require Node.js-based compilation.
• Duplicating autoprefixing or minification logic in both a LESS plugin and a separate PostCSS step.
• Not pinning a community plugin's version, risking unexpected behavior changes on a routine dependency update.

Key Takeaways

• LESS plugins register custom JavaScript functions or compiler behavior, loaded via @plugin "name";.
• Plugins run only during compilation and add no runtime JavaScript to the compiled CSS output.
• Prefer established community plugins for common needs like minification or glob-based imports.
• Route final-CSS-only concerns (like autoprefixing) through a dedicated post-processing tool rather than a custom LESS plugin.