Unification of plugin subsystems.

[seven-phases-max]

As was already mentioned initially (and then in #10 and in various topics here and there), @plugin feature needs further improvements as its current implementation was just a temporary solution to get something in the release ASAP.

So the very first step for the unification would be to allow the @plugin directive to load both formats, i.e.:

@plugin "clean-css";

• first try to load the "standard" format, i.e. less-plugin-clean-css (in the directories specified in the docs)
• and only then try to load clean-css.js file (of the "easy-functions" format, in the directories of the compiled less project).

Contrary:

@plugin "clean-css.js";

looks directly for an "easy-functions" clean-css.js file.

---

As also mentioned earlier, loading "standard format" plugins with @plugin directive is expected to have certain acceptable limitations/restrictions to work properly (e.g. no special scoping and the directive should appear before any code it may have an effect on (specifically for "visitor" plugins)).

---

Setting "standard format" options via @plugin are yet to be specified later. Obviously the options will be set via typical @import/@media-like syntax, e.g.:

@plugin (s1, advanced, compatibility: ie8) "clean-css";

But exact implementation details to be set up later.

[matthew-dean]

Good start. I'm actually less familiar with what you call the "standard format" plugins because the usage always seemed overly complex, so I never bothered with it. But @plugin plugins are a no-brainer. They're easy to write and they always work. Part of the reason they're easy is because they're limited, which is actually a good feature.

In any case, I don't see anything in the docs pertaining to directory location of the old plugin format. The plugin file actually has to be "pre-loaded", does it not? So I don't think Less looks for it anywhere. Whereas @plugin just follows typical @import Less rules. The plugin file should be with your "Less project" somewhere, which you need to reference explicitly.

---

Having @plugin do a special search first to prepend "less-plugin" on the name of the file seems like a regression. IMO it should continue to follow current @import/@plugin behavior of searching exactly the file you just wrote, in the relative or absolute directory you specified (barring any modifications of directory searching in your initial Less options).

If an author wants to follow a convention of using "less-plugin-" but wants to shorten the reference, they can just easily write:

@p: "less-plugin";
@plugin "@{p}-clean-css";

Or whatever else they want to do there. Adding two specific words in the name of a JavaScript file doesn't make sense to make a dedicated feature, since names of files are arbitrary. AND, if they want plugins to do such prepending automatically, they can just add a "less-plugin-" prepending plugin! 😉

@plugin "less-plugins";
@plugin "clean-css";

(Although the latter wouldn't be recommended, since it would be altering any plugin reference used anywhere. But still, it's an option.)

---

I agree that adding "options" to plugins can be discussed later.

[seven-phases-max]

Having @plugin do a special search first to prepend "less-plugin" on the name of the file seems like a regression

It depends. Here you're thinking (as @rjgotten also most likely did when submitting the initial @plugin PR) as someone who is just about to write and use his own project specific custom functions. But (not putting any IMHO, but it's obviously assumed anywhere anyway) the general auditory is just about:

• npm install (-g) less-plugin-stdlib (the prefix is actually optional and used only to easily identify Less plugins among other nmp-modules)
• @plugin "stdlib";

We can get back to less/less.js#1861 (comment) and start all over again from scratch of course. But this is how the "standard format" works (lessc --stdlib) and I don't see any reason for @plugin to not follow this convention.

searching exactly the file you just wrote

@plugin "path-to/the-file-you-just-wrote.js";

In any case, I don't see anything in the docs pertaining to directory location of the old plugin format.

Then it is the issue of the docs to be fixed.

---

Also speaking of the "old format". I guess we have to clarify this. The "standard format" is no way "the old" but actually the one and the only format. You may be less familiar with it but it's the only way by now to make something beside custom functions, so I recommend you to get more familiar with it and start looking where it has to be improved to meet your vision. Otherwise you're risking to continuously reinvent the wheel by proposing parallel incompatible solutions (like less/less.js#2852).

In other words, it's not about making the @plugin to be able to do what "standard format" can do, but just about making the current @plugin implementation to conform to the "standard format". Otherwise I'm afraid we definitely need to stop, disable both features, get back to less/less.js#1861 and start redesigning everything from scratch.

[matthew-dean]

Also speaking of the "old format". I guess we have to clarify this. The "standard format" is no way "the old" but actually the one and the only format. You may be less familiar with it but it's the only way by now to make something beside custom functions, so I recommend you to get more familiar with it and start looking where it has to be improved to meet your vision.

That's fair. But what I meant was that we had talked about moving plugins to be loadable under @plugin, and I wasn't sure that the "standard format" was compatible with that model.

But this is how the "standard format" works (lessc --stdlib) and I don't see any reason for @plugin to not follow this convention.

This is also a good point. I see where you're coming from. I had assumed that a) backward compatibility was not possible because of the way plugins are loaded, b) the solution might have to be to deprecate plugin format A, and have plugin format B (@plugin) have the same technical capability as the current format but I wasn't sure that it could be compatible with the way plugins are currently written.

But, you're not seeing them as "two formats", so much as a newer way (and maybe easier way) to call a Less plugin.

In other words, it's not about making the @plugin to be able to do what "standard format" can do, but just about making the current @plugin implementation to conform to the "standard format".

I hear you. Thank you for clarifying. One advantage we have is that I think we can classify the current @plugin implementation as "experimental" (since it's not yet documented), and so therefore it shouldn't need any official "deprecation" for any possible breaking changes (although it would be nice to avoid).

[matthew-dean]

One comment about loading order, though, as far as to which one is first. I still think the "explicit name" should be checked first. The original docs say, "We recommend the plugin starts "less-plugin" though that isn't required."

"less-plugin" is supported, but it still seems like a convenience addition that it's checked after the explicit name is checked, as the name is an optional recommendation. So I think the name check would happen more like:

@plugin "clean-css";

1. Check for npm installed "clean-css" plugin (or loaded file in the browser?).
2. Check for "clean-css.js" relative to the Less file that just called it.
3. Check for npm installed "less-plugin-clean-css" plugin.
4. Check for "less-plugin-clean-css.js" relative to the Less file that just called it.

There's bridging @plugin to current plugin implementations, but there's also bridging standard Less plugins to other file referencing conventions in Less. IMO convenience methods should typically be a fallback.

[seven-phases-max]

Well, my proposal of the order is based solely on "the better performance for the masses" sense of view. Yet again assuming the majority of users will use "public/shared" modules (which will have the prefix for obvious reasons) instead of self-written plugins, it would make sense to not burden the majority with additional search step that rarely matches anyway.
(Though with or without prefix and with or without extension, it still would make sense to first look for the local installation and only then for the global. Now the only problem is to define what is "local" in relativity to the current Less file (unlike node, Less does not have a concept of the "project directory" (usually it's assumed to be the directory of the master less file but it's not always the case)).

The only concern is the "browser-side" plugins: obviously since a node-based plugin has to be browserified somehow before to be used client-side, and that browserified version also ends in plugin.js file we have to introduce some artificial marker to distinguish between two formats (assuming we'll keep the "easy functions" format at least for the backward-compatibility even if it's totally overlapped with the "standard format").

[matthew-dean]

Yet again assuming the majority of users will use "public/shared" modules (which will have the prefix for obvious reasons) instead of self-written plugins, it would make sense to not burden the majority with additional search step that rarely matches anyway.

A public/shared module does not automatically mean an "npm-installed" one. The jQuery plugin ecosystem does not rely on Node as a dependency, and I don't think Less should either. Officially, Less is platform-agnostic. To me, that means that "core Less" should assume nothing other than the file reference you gave is a valid, local file. True, the platform extensions can then define what is "valid and local". So, it would make sense that the Node platform extension might have a different search mechanism / order than what happens in-browser.

As an example that you're drawing from for convention: lessc is a platform-specific Node extension of Less.js, albeit an official one. So, by definition, the features of lessc are not universal, nor are the conventions.

I think, conventionally, Less plugins have basically been "Node-only", partly because they rely on NPM, and partly because they're written in such a way that excludes the browser (relies on Node as a dependency). I think that's part of what has limited plugin adoption and ease-of-use, so I wouldn't want to see that entirely as a guiding principle.

For instance, there are currently "Less plugins" that rely on NPM, explictly say they don't work in the browser, but are nothing more than additional Less functions. That's wholly unnecessary. I think for a successful plugin ecosystem, we should guide developers to create platform-agnostic Less plugins, since Less itself is platform-agnostic. Just like there were mistakes made with the initial @plugin implementation, I believe there were mistakes made with the initial plugin implementation in 2.0.

Which certainly doesn't mean that we should break those plugins on a whim. I just want to really focus on:

1. What makes plugins easy to write
2. What makes plugins easy to use

I think those are the two most-essential pieces of a successful plugin system. If, in our documentation, we give examples that suggest, "It's okay to create a Node-only plugin", then we're effectively saying that Node is really the only valid Less environment, which makes non-Node/NPM plugin scenarios harder to use.

So as to:

The only concern is the "browser-side" plugins: obviously since a node-based plugin has to be browserified somehow before to be used client-side

I think we should caution people against making "Node-side" or "browser-side" plugins as much as possible. Or at least thinking if such a thing is absolutely necessary. Rather than thinking of Less as a Node-based system that you add to with NPM-hosted plugins, it might be easier for some users to treat Less plugins like jQuery ones, where the plugins travel with the associated Less project, not that get installed somewhere "in-system", as those have dependencies which are not portable. Less plugins can easily exist as a single JS file which gets copied into your local Less source file directory.

But, the nice thing is that if we do things right, we don't have to adopt either "philosophy". Someone could choose to manage their Less plugins via NPM, and another person could copy and paste a file. If we write guidelines and examples appropriately, people can have the best of both worlds.

[matthew-dean]

Just as an example as far as cross-platform plugin conventions, I've seen a library like Ractive (which can run in both browser and Node), basically do conventions as:

• Plugins either exist as a single file, or include a dist/ directory with a single file that can be used in-browser (similar to what Less itself does)
• Plugins basically have Node consumption and browser consumption instructions as a standard part of each plugin repo

One thing that PostCSS does is it has a plugin generation script which creates your initial repo. So, we could do something similar where someone enters the name of their plugin, and it does the following:

1. Sets up a package.json file, a dist/ folder, an initial index.js file (for NPM/Node), and both build and test scripts for the plugin
2. Populates the documentation to demonstrate Node usage via "npm install" and via @plugin.
3. Demonstrates in-browser use of the distribution file (possibly without the "less-plugin-" prefix? Or as an option when generating the repo?) with @plugin

[seven-phases-max]

a plugin generation script which creates your initial repo.

This is probably better to be done with something like Yeoman (though personally I'm not very familiar with it since it was broken for my dev-platform for a while).

[matthew-dean]

Yeoman may be what was/is used, in fact. So, yep, something along those lines.

[rjgotten]

Here you're thinking (as @rjgotten also most likely did when submitting the initial @plugin PR) as someone who is just about to write and use his own project specific custom functions.

Actually; I wrote @plugin the way I wrote it, to transparantly support plugins being included via transitive closure, i.e. , as dependencies of dependencies, without bothering the consumer (developer) of the Less file that imports the first dependency.

It was meant as a zero-setup, collision-free means to include custom functions for Less frameworks.

The zero-setup aspect makes it work transparantly with any side-by-side editor that calls out to Lessc to create CSS previews, without having to mess with custom settings. That's an additional perk and may be a good reason to also develop your own project-specific functions in the @plugin format.

we have to introduce some artificial marker to distinguish between two formats

Imports may use URLs, so why not @plugin "node://clean-css" to instruct the compiler to use the NodeJS module lookup rules.

[seven-phases-max]

so why not @plugin "node://clean-css"

same mistake as:

A public/shared module does not automatically mean an "npm-installed" one.

Notice there's no mention of node or npm in the initial post.

@plugin "clean-css";

is fine to load PHP-written (optionally even particular platform-specific, e.g. Wordpress) less-plugin-clean-css in less.php for example.

---

It was meant as a zero-setup, collision-free means to include custom functions for Less frameworks.

This is illusion (no offense meant :) - it stops to be true as soon as you start to share the same plugin in different projects (so you either need a copy of the plugin in each or setup the shared paths, thus -> no zero-setup) or start to use different libraries that include different versions of the same plugin (so sooner or later someone comes with an idea of 'Less plugin manager/packager' utility).

So in general it's all the same problems whatever approach you choose.

[matthew-dean]

This is illusion (no offense meant :) - it stops to be true as soon as you start to share the same plugin in different projects (so you either need a copy of the plugin in each or setup the shared paths, thus -> no zero-setup) or start to use different libraries that include different versions of the same plugin (so sooner or later someone comes with an idea of 'Less plugin manager/packager' utility).

Different versions of the same plugin are only an issue if you use NPM to manage your plugins. NPM is famously terrible and being able to install multiple versions to use simultaneously.

The way @rjgotten wrote it seems like it would work fine in that scenario, since functions are scoped, and the included JS file doesn't contain any sort of unique identifier that can collide if you have multiple copies. Therefore, you should be able to do:

#library1 {
  @plugin "library1/foo-plugin.js";
  bar: foo(); 
}
#library2 {
  @plugin "library2/foo-plugin.js";  // same plugin, different version
  bar: foo();
}

Standard/current format plugins modify Less at the core/root level, and so are inherently prone to collisions in the way you describe. Currently @plugin functions are not. It's one of the reasons that I feel that the copy/paste of a distribution file is actually the more appropriate recommended method. It can get included in the source files right where you need it.

And then you have everything that "builds" your final CSS file all in one place. It's not pulling your Less file from a local directory and then a JS file from some other place, even though they have similar URL paths.

The way I visualize this is like:

[matthew-dean]

I also agree though that this is probably the wrong way to go:

@plugin "node://clean-css"

Unless...... like the way that "less-plugin-" is magically prepended for lessc, we assign a meaning to the browser. (The browser knows to look in node_modules.)

That said, it's such a specific case that, again, the "node://" URL scheme should itself be supported by a plugin. With proper architecture and good documentation, we can keep the core light and support those kinds of customizations better.

I've said it before in other threads: there's no reason there can't be official plugins that pull in optional JS files. We have official platform extensions, so something that searches node_modules/ could be a supported plugin. A benefit to having official plugins is to help establish plugin convention.

[rjgotten]

That said, it's such a specific case that, again, the "node://" URL scheme should itself be supported by a plugin.

Ah. You beat me to it. Yeah; that was going to be my argument as well.

Also, just for the record: Node.js module lookup is different from what Lessc is currently using. Lessc is using require in its plugin loader, alright, but it searches an opinionated number of folders in a non-standard order, rather than following the node module lookup algorithm. (Look up the maddening details of the lookup algorithm at your own risk.

So it should be called something different from node:// anyway.